PHPackages                             freema/simdjson-polyfill - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. freema/simdjson-polyfill

ActiveLibrary[Utility & Helpers](/categories/utility)

freema/simdjson-polyfill
========================

🚀 Automatic simdjson integration for PHP with multiple override strategies. Drop-in replacement for json\_decode() with 3x performance boost. Symfony, Nette & Laravel support included.

v1.1.0(6mo ago)041MITPHPPHP ^8.0CI passing

Since Nov 19Pushed 6mo agoCompare

[ Source](https://github.com/freema/simdjson-polyfill)[ Packagist](https://packagist.org/packages/freema/simdjson-polyfill)[ RSS](/packages/freema-simdjson-polyfill/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (8)Versions (3)Used By (0)

🚀 SimdJson Polyfill
===================

[](#-simdjson-polyfill)

[![Tests](https://github.com/freema/simdjson-polyfill/workflows/Tests/badge.svg)](https://github.com/freema/simdjson-polyfill/actions)[![Latest Stable Version](https://camo.githubusercontent.com/da96ba946a65eba668c830ec5ccab553645633ec858a62ca19c0955565db53a2/68747470733a2f2f706f7365722e707567782e6f72672f667265656d612f73696d646a736f6e2d706f6c7966696c6c2f76)](https://packagist.org/packages/freema/simdjson-polyfill)[![License](https://camo.githubusercontent.com/42ef6d5a5614b1183fd6f7a2db6a466938ffa5e7db1e297bd5220674b878a636/68747470733a2f2f706f7365722e707567782e6f72672f667265656d612f73696d646a736f6e2d706f6c7966696c6c2f6c6963656e7365)](https://packagist.org/packages/freema/simdjson-polyfill)

**Automatic [simdjson](https://github.com/simdjson/simdjson) integration for PHP with multiple override strategies.**

Get **3x faster JSON parsing** with minimal code changes. Drop-in replacement for `json_decode()` with Symfony, Nette & Laravel support included.

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Why SimdJson?](#why-simdjson)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Strategies](#strategies)
- [Framework Integration](#framework-integration)
- [Benchmarks](#benchmarks)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

🎯 Why SimdJson?
---------------

[](#-why-simdjson)

[simdjson](https://simdjson.org/) is the world's fastest JSON parser, using SIMD instructions to parse JSON at speeds approaching 3 GB/s. This library makes it trivial to use simdjson in your PHP applications.

**Performance gains:**

- 🚀 **3x faster** JSON parsing compared to native `json_decode()`
- ⚡ Perfect for APIs processing large JSON payloads
- 💾 Lower CPU usage and better resource utilization
- 🔥 Zero-copy parsing when possible

📋 Requirements
--------------

[](#-requirements)

- PHP 8.0 or higher (tested on PHP 8.0, 8.1, 8.2, 8.3, and 8.4)
- Composer

**PHP 8.4 Note:** All strategies work on PHP 8.4 **except UopzStrategy**, which requires PHP ≤ 8.3 due to uopz extension incompatibility.

📦 Installation
--------------

[](#-installation)

```
composer require freema/simdjson-polyfill
```

**Optional (for best performance):**

```
# Install simdjson PHP extension
pecl install simdjson
```

**Optional (for advanced strategies):**

```
# Install UOPZ extension for global override
pecl install uopz
```

🚀 Quick Start
-------------

[](#-quick-start)

### Option 1: Safe Polyfill (Recommended)

[](#option-1-safe-polyfill-recommended)

Use `JsonDecoder::decode()` or `fast_json_decode()` instead of `json_decode()`:

```
use SimdJsonPolyfill\JsonDecoder;

// Using static method
$data = JsonDecoder::decode($json, true);

// Or using helper function
$data = \SimdJsonPolyfill\fast_json_decode($json, true);
```

### Option 2: Auto-Enable (Magic Mode)

[](#option-2-auto-enable-magic-mode)

Automatically use the best available strategy:

```
use SimdJsonPolyfill\SimdJsonPolyfill;

// Enable once at application bootstrap
SimdJsonPolyfill::enable();

// Now json_decode() uses simdjson (if using aggressive strategies)
// Or use JsonDecoder::decode() for safe polyfill
```

### Option 3: Explicit Strategy

[](#option-3-explicit-strategy)

Choose a specific strategy:

```
use SimdJsonPolyfill\SimdJsonPolyfill;

// Use UOPZ to override json_decode() globally
SimdJsonPolyfill::enable([
    'strategy' => 'uopz',
    'allow_in_production' => true, // Required for production
]);

// Now ALL json_decode() calls use simdjson!
$data = json_decode($json, true);
```

🎛️ Strategies
-------------

[](#️-strategies)

SimdJson Polyfill offers multiple strategies with different trade-offs:

StrategyRisk LevelPerformanceGlobal OverrideRequires Extension**PolyfillStrategy**✅ SafeHighNo`ext-simdjson`**UopzStrategy**⚠️ RiskyHighestYes`ext-uopz`, `ext-simdjson`**NamespaceStrategy**⚠️ MediumHighPer-namespace`ext-simdjson`**AutoPrependStrategy**⚠️ MediumHighYes (manual)`ext-simdjson`**ComposerPluginStrategy**🔥 Very RiskyHighYes (build-time)`ext-simdjson`, `nikic/php-parser`### 1. PolyfillStrategy (Safe, Default)

[](#1-polyfillstrategy-safe-default)

**Recommended for most use cases.**

Provides `JsonDecoder::decode()` and `fast_json_decode()` functions. No magic, no risks.

```
use SimdJsonPolyfill\JsonDecoder;

$data = JsonDecoder::decode($jsonString, true);
```

**Pros:**

- ✅ Zero risk - no global side effects
- ✅ Works everywhere
- ✅ Easy to test and debug

**Cons:**

- ❌ Requires code changes to use new functions
- ❌ Won't affect third-party code

### 2. UopzStrategy (Risky, Powerful)

[](#2-uopzstrategy-risky-powerful)

**⚠️ WARNING: Modifies runtime behavior globally!**

Uses the [UOPZ extension](https://www.php.net/manual/en/book.uopz.php) to override `json_decode()` at runtime.

```
SimdJsonPolyfill::enable([
    'strategy' => 'uopz',
    'allow_in_production' => true, // Required!
]);

// Now ALL json_decode() calls use simdjson
$data = json_decode($json, true);
```

**Pros:**

- ✅ Zero code changes needed
- ✅ Affects vendor code too
- ✅ Can be toggled on/off

**Cons:**

- ⚠️ Requires `ext-uopz`
- ⚠️ May have unexpected side effects
- ⚠️ Disabled in production by default
- ❌ **Not compatible with PHP 8.4+** (uopz doesn't support PHP 8.4 due to ZEND\_EXIT opcode removal)

### 3. NamespaceStrategy (Medium Risk)

[](#3-namespacestrategy-medium-risk)

Generates namespace-specific `json_decode()` functions.

```
SimdJsonPolyfill::enable([
    'strategy' => 'namespace',
    'namespaces' => ['App\\Services', 'App\\Controllers'],
    'output_dir' => '/tmp/simdjson-functions',
]);
```

**Pros:**

- ✅ Scoped to specific namespaces
- ✅ More controlled than UOPZ

**Cons:**

- ❌ Requires namespace configuration
- ❌ Generated files need to be autoloaded

### 4. AutoPrependStrategy (Medium Risk)

[](#4-autoprependstrategy-medium-risk)

Generates a file for PHP's `auto_prepend_file` directive.

```
SimdJsonPolyfill::enable([
    'strategy' => 'auto-prepend',
    'output_file' => '/var/www/simdjson-prepend.php',
]);

// Then configure php.ini:
// auto_prepend_file = "/var/www/simdjson-prepend.php"
```

**Pros:**

- ✅ Global override without UOPZ
- ✅ Works for all PHP scripts

**Cons:**

- ⚠️ Requires php.ini configuration
- ⚠️ Affects entire PHP environment

### 5. ComposerPluginStrategy (Very Risky)

[](#5-composerpluginstrategy-very-risky)

**🔥 EXTREMELY RISKY: Modifies vendor code using AST rewriting!**

Rewrites `json_decode()` calls in vendor/ at install time.

```
SimdJsonPolyfill::enable([
    'strategy' => 'composer-plugin',
    'i_understand_the_risks' => true, // Required!
    'create_backups' => true,
    'exclude_patterns' => ['*/tests/*'],
]);
```

**Pros:**

- ✅ Build-time modification
- ✅ No runtime overhead

**Cons:**

- 🔥 Modifies third-party code
- 🔥 May break updates
- 🔥 Creates .bak files everywhere
- 🔥 **Never auto-detected, always explicit**

🔌 Framework Integration
-----------------------

[](#-framework-integration)

### Symfony

[](#symfony)

```
// config/bundles.php
return [
    // ...
    SimdJsonPolyfill\Bridge\Symfony\SimdJsonBundle::class => ['all' => true],
];
```

```
# config/packages/simdjson.yaml
simdjson:
    enabled: true
    strategy: auto  # or: polyfill, uopz, namespace, etc.
    auto_detect: true

    # UOPZ strategy config
    uopz:
        allow_in_production: false

    # Namespace strategy config
    namespace:
        namespaces:
            - 'App\Service'
            - 'App\Controller'
        output_dir: '%kernel.cache_dir%/simdjson'
```

### Laravel

[](#laravel)

```
// config/app.php (Laravel 10 and below)
'providers' => [
    // ...
    SimdJsonPolyfill\Bridge\Laravel\SimdJsonServiceProvider::class,
];
```

**Laravel 11+** uses auto-discovery, no manual registration needed!

```
# Publish configuration (optional)
php artisan vendor:publish --provider="SimdJsonPolyfill\Bridge\Laravel\SimdJsonServiceProvider" --tag="config"
```

```
// config/simdjson.php
return [
    'enabled' => env('SIMDJSON_ENABLED', true),
    'strategy' => env('SIMDJSON_STRATEGY', 'auto'),
    'auto_detect' => env('SIMDJSON_AUTO_DETECT', true),

    'uopz' => [
        'allow_in_production' => env('SIMDJSON_UOPZ_ALLOW_PRODUCTION', false),
    ],

    'namespace' => [
        'namespaces' => [
            // 'App\Services',
            // 'App\Http\Controllers',
        ],
        'output_dir' => storage_path('framework/simdjson'),
    ],
];
```

**.env configuration:**

```
SIMDJSON_ENABLED=true
SIMDJSON_STRATEGY=auto
SIMDJSON_AUTO_DETECT=true
```

### Nette

[](#nette)

```
// config/common.neon
extensions:
    simdjson: SimdJsonPolyfill\Bridge\Nette\DI\SimdJsonExtension

simdjson:
    enabled: true
    strategy: auto
    autoDetect: true

    namespace:
        namespaces:
            - App\Services
            - App\Presenters
```

📊 Benchmarks
------------

[](#-benchmarks)

Results from benchmarking on PHP 8.3:

```
========================================
SimdJsonPolyfill Benchmark
========================================
Iterations: 10000
PHP Version: 8.3.27
simdjson extension: YES
========================================

===== File: small.json (3.3 KB) =====
json_decode             98.26 ms (0.010 ms/op) | memΔ:     4 KB | peakΔ:      0 B
simdjson_decode         35.67 ms (0.004 ms/op) | memΔ:     4 KB | peakΔ:      0 B
➡️  simdjson_decode is approximately 2.75x faster (wall-time)
simdjson (polyfill)     35.69 ms (0.004 ms/op) | memΔ:     4 KB | peakΔ:      0 B

===== File: medium.json (50.6 KB) =====
json_decode            926.56 ms (0.093 ms/op) | memΔ:     4 KB | peakΔ:      0 B
simdjson_decode        379.83 ms (0.038 ms/op) | memΔ:     4 KB | peakΔ:      0 B
➡️  simdjson_decode is approximately 2.44x faster (wall-time)
simdjson (polyfill)    378.66 ms (0.038 ms/op) | memΔ:     4 KB | peakΔ:      0 B

===== File: large.json (101.1 KB) =====
json_decode          1,833.82 ms (0.183 ms/op) | memΔ:     4 KB | peakΔ:      0 B
simdjson_decode        792.74 ms (0.079 ms/op) | memΔ:     4 KB | peakΔ:      0 B
➡️  simdjson_decode is approximately 2.31x faster (wall-time)
simdjson (polyfill)    779.16 ms (0.078 ms/op) | memΔ:     4 KB | peakΔ:      0 B

===== File: xlarge.json (500.7 KB) =====
json_decode          9,130.94 ms (0.913 ms/op) | memΔ:     4 KB | peakΔ:   1.8 MB
simdjson_decode      3,752.57 ms (0.375 ms/op) | memΔ:     4 KB | peakΔ:    376 B
➡️  simdjson_decode is approximately 2.43x faster (wall-time)
simdjson (polyfill)  3,751.59 ms (0.375 ms/op) | memΔ:     4 KB | peakΔ:    376 B

```

**Run benchmarks yourself:**

```
task benchmark
# or
docker-compose run --rm php php tests/Benchmark/JsonDecodeBenchmark.php
```

🐳 Development
-------------

[](#-development)

This project uses Docker for development and testing, with [Task](https://taskfile.dev/) as the build tool.

### Prerequisites

[](#prerequisites)

Install Task:

```
# macOS
brew install go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Or see https://taskfile.dev/installation/
```

### Setup

[](#setup)

```
# Build containers
task build

# Install dependencies
task install

# Generate benchmark fixtures
task fixtures
```

### Testing

[](#testing)

```
# Run all tests
task test

# Run tests with coverage
task test-coverage

# Test on all PHP versions
task test-all

# Run static analysis
task stan
```

### Benchmarking

[](#benchmarking)

```
# Generate fixtures
task fixtures

# Run benchmarks
task benchmark
```

### Available Commands

[](#available-commands)

```
task --list          # Show all available commands
task shell           # Open shell in PHP container
task install         # Install Composer dependencies
task test            # Run PHPUnit tests
task benchmark       # Run benchmarks
task clean           # Clean up containers and dependencies
```

⚠️ Warnings and Best Practices
------------------------------

[](#️-warnings-and-best-practices)

### When to Use Which Strategy

[](#when-to-use-which-strategy)

**Production Applications:**

- ✅ Use **PolyfillStrategy** - Safe, predictable, testable
- ⚠️ Consider **UopzStrategy** only if you thoroughly test

**Development/Staging:**

- ✅ Any strategy is fine for experimentation

**Never Use:**

- 🚫 **ComposerPluginStrategy** in production
- 🚫 **AutoPrependStrategy** without extensive testing

### Safety Tips

[](#safety-tips)

1. **Always test in staging first**
2. **Monitor for edge cases** - simdjson may parse JSON slightly differently
3. **Have a rollback plan** - disable with one config change
4. **Check compatibility** - some JSON edge cases may behave differently
5. **Use version control** - especially with ComposerPluginStrategy

🧪 Testing
---------

[](#-testing)

```
# Unit tests
vendor/bin/phpunit

# With Docker
make test

# Test specific PHP version
make test-83

# Test all versions
make test-all
```

📄 License
---------

[](#-license)

MIT License. See [LICENSE](LICENSE) file for details.

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

🔗 Links
-------

[](#-links)

- [simdjson](https://github.com/simdjson/simdjson) - The original C++ library
- [simdjson PHP extension](https://github.com/crazyxman/simdjson_php) - PHP extension for simdjson
- [Packagist](https://packagist.org/packages/freema/simdjson-polyfill)
- [GitHub](https://github.com/freema/simdjson-polyfill)

📮 Support
---------

[](#-support)

- **Issues:** [GitHub Issues](https://github.com/freema/simdjson-polyfill/issues)
- **Discussions:** [GitHub Discussions](https://github.com/freema/simdjson-polyfill/discussions)

---

Made with ❤️ by [Tomas Grasl](https://github.com/freema)

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance69

Regular maintenance activity

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

181d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1feadbd856db0d9578f7e3c5221c76bd76d4cdfa745bd748be918b2cd10de70c?d=identicon)[Freema](/maintainers/Freema)

---

Top Contributors

[![freema](https://avatars.githubusercontent.com/u/2912985?v=4)](https://github.com/freema "freema (13 commits)")

---

Tags

laravelnette-frameworkphpphp-extensionphp-librarysymfonypolyfilljsonsymfonylaravelnetteperformancesimdjson

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/freema-simdjson-polyfill/health.svg)

```
[![Health](https://phpackages.com/badges/freema-simdjson-polyfill/health.svg)](https://phpackages.com/packages/freema-simdjson-polyfill)
```

###  Alternatives

[kris/laravel-form-builder

Laravel form builder - symfony like

1.7k2.2M45](/packages/kris-laravel-form-builder)[brexis/laravel-workflow

Integerate Symfony Workflow component into Laravel.

283125.6k](/packages/brexis-laravel-workflow)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)