README

SIMD-accelerated JSON parsing for PHP via sonic-rs.

Features

• Lazy Parsing: Extract specific values from massive JSON documents without full DOM construction
• Query API: Chainable, fluent interface that stays in Rust until hydration
• SIMD Acceleration: Uses modern CPU instructions for parallel JSON processing
• Memory Efficient: Zero-copy parsing minimizes allocations
• Security Hardened: Input size limits, depth limits, and overflow protection
• PHP 8.x Compatible: Works with PHP 8.1+

Requirements

• PHP 8.1+ with development headers (php-dev)
• Rust 1.70+ (stable)
• Docker (recommended for development)

Installation

Using Docker (Recommended)

# Build and test in Docker
make docker-test

# Interactive development shell
make docker-shell

Local Build

Requires PHP development headers installed:

# Ubuntu/Debian
sudo apt-get install php-dev

# Install cargo-php
cargo install cargo-php

# Build and install the extension
cargo php install --release

# Verify installation
php -m | grep sonic

Composer (for IDE Support)

After installing the extension, add Composer support for IDE autocompletion:

composer require dmytrokucher/sift

This provides stub files for the Sonic, Sift, and Query classes, enabling full IDE autocompletion and type hints.

Note: Composer does not install the extension itself - you must build and install it first using one of the methods above.

API Reference

Legacy API (Sonic class)

Sonic::get(string $json, string $pointer): mixed

Extract a value by JSON pointer (RFC 6901) without full decode.

$json = '{"users": [{"id": 1, "email": "alice@example.com"}]}';

// Extract specific value - no full parsing needed
$email = Sonic::get($json, '/users/0/email');
// Returns: "alice@example.com"

Sonic::decode(string $json): mixed

High-speed replacement for json_decode().

$data = Sonic::decode('{"name": "sonic", "fast": true}');
// Returns: ["name" => "sonic", "fast" => true]

Sonic::isValid(string $json): bool

SIMD-accelerated JSON validation.

if (Sonic::isValid($userInput)) {
    $data = Sonic::decode($userInput);
}

Modern API (Sift class)

The Sift class provides the same methods as Sonic, plus the Query API.

Sift::query(string $json): Query

Create a lazy Query object for chainable JSON navigation.

$json = '{"users": [{"id": 1, "email": "alice@example.com", "active": true}]}';

// Chainable navigation - stays in Rust until hydration
$email = Sift::query($json)
    ->get('users')
    ->index(0)
    ->get('email')
    ->string();
// Returns: "alice@example.com"

Query API Methods

Navigation (returns Query)

Hydration (extracts value)

Type Checking

Query Example

$json = '{"users": [{"id": 1, "profile": {"email": "alice@example.com"}}]}';

// Create query once, reuse for multiple extractions
$users = Sift::query($json)->get('users');

$email0 = $users->index(0)->get('profile')->get('email')->string();

// Using pointer syntax
$email = Sift::query($json)->pointer('/users/0/profile/email')->string();

// Type checking before extraction
$q = Sift::query($json)->pointer('/users/0');
if ($q->isObject()) {
    $user = $q->value();
}

// Get raw JSON without parsing
$rawUsers = Sift::query($json)->get('users')->raw();
// Returns: '[{"id": 1, "profile": {"email": "alice@example.com"}}]'

JSON Pointer Syntax

JSON pointers follow RFC 6901:

Security

Sift includes several security hardening measures:

Benchmarks

Run benchmarks after installation:

make bench

Expected Results

Results vary by hardware and JSON structure

Development

# Run all tests
make test

# Run PHP tests only (requires extension installed)
make test-php

# Run tests in Docker
make docker-test

# Format code
make fmt

# Lint code
make lint

Architecture

See ARCHITECTURE.md for details on:

• Memory management between PHP's Zend Arena and Rust's ownership model
• Query API lazy evaluation design
• SIMD optimization strategies
• Security measures and limits
• Error handling across the FFI boundary

Acknowledgements

This project builds on excellent open-source libraries:

• sonic-rs - The SIMD-accelerated JSON engine (Apache-2.0)
• ext-php-rs - PHP/Rust bindings (MIT/Apache-2.0)

See NOTICE file for full attribution.

License

MIT License - see LICENSE file for details.