PHPackages                             farzai/json-serializer - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. farzai/json-serializer

ActiveLibrary[Parsing & Serialization](/categories/parsing)

farzai/json-serializer
======================

High-performance JSON serializer for PHP with streaming support, type-safe object mapping, and memory-efficient processing.

0.1.0(6mo ago)01[4 PRs](https://github.com/parsilver/json-serializer-php/pulls)MITPHPPHP ^8.1CI passing

Since Oct 30Pushed 1mo agoCompare

[ Source](https://github.com/parsilver/json-serializer-php)[ Packagist](https://packagist.org/packages/farzai/json-serializer)[ Docs](https://github.com/parsilver/json-serializer-php)[ GitHub Sponsors](https://github.com/parsilver)[ RSS](/packages/farzai-json-serializer/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (7)Versions (6)Used By (0)

JSON Serializer for PHP
=======================

[](#json-serializer-for-php)

[![Latest Version on Packagist](https://camo.githubusercontent.com/6d481ebea6f9d45519bb071efcfe59ed5cceef8dd514fe8ee9a076288193c41a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6661727a61692f6a736f6e2d73657269616c697a65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/farzai/json-serializer)[![Tests](https://camo.githubusercontent.com/048215272eae2b6ccaa77ec06467ec374b6f1e448e417bd425fe10f6da63d3f7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70617273696c7665722f6a736f6e2d73657269616c697a65722d7068702f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/parsilver/json-serializer-php/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/af943ba41282db1a0e6ef7bdb009b63bb8d1edefc63853a9e2f914e11de56336/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6661727a61692f6a736f6e2d73657269616c697a65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/farzai/json-serializer)

A high-performance, type-safe JSON serializer and deserializer for PHP 8.1+ with advanced features including attribute-based configuration, nested object support, versioning, transformers, and comprehensive error handling.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require farzai/json-serializer
```

Features
--------

[](#features)

- **High Performance** - Optimized for speed and memory efficiency
- **Generator Support** - Memory-efficient serialization of large datasets using PHP generators
- **Type-Safe** - Full PHP 8.1+ type system support including union types
- **Nested Objects** - Automatic recursive serialization/deserialization
- **Collections** - `array` notation for typed collections
- **Attributes** - Powerful attribute-based configuration
- **Versioning** - API versioning with `#[Since]` and `#[Until]`
- **Transformers** - Custom transformers for DateTime, Enums, and more
- **Naming Strategies** - snake\_case, camelCase, PascalCase, kebab-case
- **Virtual Properties** - Computed properties from methods
- **Error Handling** - Detailed error messages with property paths
- **Circular Reference Detection** - Automatic detection and prevention
- **Max Depth Control** - Configurable depth limits
- **Type Coercion** - STRICT, SAFE, and LENIENT modes for flexible type handling

When to Use This Library
------------------------

[](#when-to-use-this-library)

### ✅ Use This Library When:

[](#-use-this-library-when)

- **Type-Safe Object Mapping**: You need to deserialize JSON into strongly-typed PHP objects
- **API Versioning**: Your API supports multiple versions with `#[Since]` and `#[Until]` attributes
- **Large File Processing**: You need to process JSON files > 100MB without memory issues
- **Advanced Features**: You need transformers, virtual properties, or custom naming strategies
- **Attribute-Based Config**: You prefer declarative configuration over imperative code
- **Streaming Operations**: You need to process JSON incrementally or extract specific paths

### ⚠️ Use Native Functions When:

[](#️-use-native-functions-when)

- **Simple Arrays**: Basic `json_encode(['key' => 'value'])` for simple data structures
- **Maximum Performance**: Serialization speed is critical and you don't need advanced features
- **Small Data**: Processing < 1KB of data where overhead doesn't matter
- **No Type Safety Needed**: You're comfortable working with untyped arrays

### Performance Trade-offs

[](#performance-trade-offs)

**Serialization**: ~50-60x slower than native `json_encode` due to rich features

- Native: 1.0μs for small data, 3.6ms for 10MB
- This library: 49μs for small data, 204ms for 10MB
- **Recommendation**: Use native functions for hot paths where features aren't needed

**Deserialization**: Competitive with native `json_decode` (~1.0x speed)

- Native: 942μs for 1MB, 9.9ms for 10MB
- This library: 936μs for 1MB, 10.0ms for 10MB
- **Recommendation**: Safe to use everywhere for deserialization with type-safe object mapping

**Memory**: Only ~7% overhead compared to native functions

Usage
-----

[](#usage)

### Basic Serialization

[](#basic-serialization)

```
use Farzai\JsonSerializer\JsonSerializer;

// Simple array to JSON
$data = ['name' => 'John', 'age' => 30];
$json = JsonSerializer::encode($data);
// {"name":"John","age":30}

// Object to JSON
class User {
    public function __construct(
        public string $name,
        public int $age
    ) {}
}

$user = new User('John Doe', 30);
$json = JsonSerializer::encode($user);
// {"name":"John Doe","age":30}

// Pretty print
$json = JsonSerializer::encode($user, prettyPrint: true);
```

### Basic Deserialization

[](#basic-deserialization)

```
// JSON to array
$json = '{"name":"John","age":30}';
$data = JsonSerializer::decode($json);
// ['name' => 'John', 'age' => 30]

// JSON to class
class User {
    public string $name;
    public int $age;
}

$user = JsonSerializer::decodeToClass($json, User::class);
// User instance with name='John', age=30

// JSON array to array of objects
$json = '[{"name":"John","age":30},{"name":"Jane","age":25}]';
$users = JsonSerializer::decodeArray($json, User::class);
// Array of User instances
```

### Nested Objects & Collections

[](#nested-objects--collections)

```
use Farzai\JsonSerializer\Attributes\Type;
use Farzai\JsonSerializer\JsonSerializer;

class Address {
    public string $street;
    public string $city;
    public string $country;
}

class Author {
    public string $name;
    public string $email;
}

class Book {
    public string $title;
    public Address $publisher;

    #[Type('array')]
    public array $authors;
}

// Deserialize nested objects and collections
$json = '{
    "title": "PHP Guide",
    "publisher": {
        "street": "123 Main St",
        "city": "NYC",
        "country": "USA"
    },
    "authors": [
        {"name": "John Doe", "email": "john@example.com"},
        {"name": "Jane Smith", "email": "jane@example.com"}
    ]
}';

$book = JsonSerializer::decodeToClass($json, Book::class);
// $book->publisher is an Address instance
// $book->authors is an array of Author instances
```

### Attributes

[](#attributes)

```
use Farzai\JsonSerializer\Attributes\{
    SerializedName,
    Ignore,
    DateFormat,
    Since,
    Until,
    VirtualProperty,
    NamingStrategy
};

#[NamingStrategy('snake_case')]
class User {
    #[SerializedName('user_id')]
    public int $id;

    public string $name;

    #[Ignore]
    public string $password;

    #[DateFormat('Y-m-d')]
    public DateTime $createdAt;

    #[Since('2.0')]
    public ?string $email = null;

    #[Until('3.0')]
    public ?string $legacyField = null;

    #[VirtualProperty]
    public function getDisplayName(): string {
        return strtoupper($this->name);
    }
}
```

### Versioning

[](#versioning)

```
// Serialize for version 1.0 (excludes email, includes legacyField)
$json = JsonSerializer::builder()
    ->withVersion('1.0')
    ->build()
    ->encode($user);

// Serialize for version 2.0 (includes email, includes legacyField)
$json = JsonSerializer::builder()
    ->withVersion('2.0')
    ->build()
    ->encode($user);

// Serialize for version 3.0+ (includes email, excludes legacyField)
$json = JsonSerializer::builder()
    ->withVersion('3.0')
    ->build()
    ->encode($user);
```

### Custom Transformers

[](#custom-transformers)

```
use Farzai\JsonSerializer\Attributes\Transformer;
use Farzai\JsonSerializer\Attributes\DateFormat;

class Event {
    public string $name;

    #[DateFormat('Y-m-d H:i:s')]
    public DateTime $startTime;

    #[DateFormat(DateFormat::ISO8601)]
    public DateTime $endTime;

    #[Transformer(MyCustomTransformer::class, ['option' => 'value'])]
    public mixed $customField;
}
```

### Union Types

[](#union-types)

```
class FlexibleData {
    public string|int $id;  // Can be string or int
    public User|null $owner; // Can be User object or null
    public string|float $value; // Can be string or float
}

$json = '{"id": "abc123", "owner": null, "value": 3.14}';
$data = JsonSerializer::decodeToClass($json, FlexibleData::class);
// Automatically handles union types
```

### Error Handling

[](#error-handling)

```
use Farzai\JsonSerializer\Exceptions\DeserializationException;

try {
    $json = '{"name":"John","address":"invalid"}'; // address should be object
    $user = JsonSerializer::decodeToClass($json, UserWithAddress::class);
} catch (DeserializationException $e) {
    echo $e->getMessage();
    // "Type mismatch during deserialization. Property path: address. Type mismatch: expected Address, got string"

    echo $e->getPropertyPath(); // "address"
    echo $e->getExpectedType(); // "Address"
    echo $e->getActualType();   // "string"
}
```

### Circular Reference Detection

[](#circular-reference-detection)

The library automatically detects and prevents circular references during serialization:

```
use Farzai\JsonSerializer\JsonSerializer;
use Farzai\JsonSerializer\Exceptions\SerializationException;

class Node {
    public string $name;
    public ?Node $parent = null;
    public ?Node $child = null;
}

// Create circular reference
$parent = new Node();
$parent->name = 'Parent';

$child = new Node();
$child->name = 'Child';
$child->parent = $parent;

$parent->child = $child; // Circular reference!

try {
    $json = JsonSerializer::encode($parent);
} catch (SerializationException $e) {
    echo $e->getMessage();
    // "Circular reference detected for object of class Node"
}

// Disable circular reference detection if needed
$serializer = JsonSerializer::builder()
    ->withCircularReferenceDetection(false)
    ->build();

// Now it will serialize (may cause infinite loop!)
$json = $serializer->encode($parent);
```

### Builder Pattern

[](#builder-pattern)

```
use Farzai\JsonSerializer\Builder\SerializerBuilder;

$serializer = SerializerBuilder::create()
    ->withVersion('2.0')
    ->withMaxDepth(100)
    ->withPrettyPrint(true)
    ->build();

$json = $serializer->encode($data);
```

### Security & Configuration

[](#security--configuration)

Protect your application from malicious or malformed JSON with built-in security features:

```
use Farzai\JsonSerializer\JsonSerializer;
use Farzai\JsonSerializer\Exceptions\SerializationException;

// Configure security limits
$serializer = JsonSerializer::builder()
    ->withMaxDepth(50)                          // Prevent deeply nested structures
    ->withCircularReferenceDetection(true)      // Detect circular references (default: true)
    ->withStrictTypes(true)                     // Enable strict type checking (default: true)
    ->build();

// Example: Max depth protection
class DeepNested {
    public ?DeepNested $child = null;
}

$root = new DeepNested();
$current = $root;
for ($i = 0; $i < 100; $i++) {
    $current->child = new DeepNested();
    $current = $current->child;
}

try {
    $json = $serializer->encode($root);
} catch (SerializationException $e) {
    echo $e->getMessage();
    // "Maximum depth of 50 exceeded"
}

// Strict types mode prevents unsafe type coercion
$strictSerializer = JsonSerializer::builder()
    ->withStrictTypes(true)
    ->build();

// Disable strict mode for more lenient serialization
$lenientSerializer = JsonSerializer::builder()
    ->withStrictTypes(false)
    ->build();
```

**Security Best Practices:**

- Always set a reasonable `maxDepth` limit (default: 512)
- Keep circular reference detection enabled for untrusted data
- Use strict types mode when deserializing external data
- Validate data structure before deserialization for critical applications

### Type Coercion Modes

[](#type-coercion-modes)

Control how the deserializer handles type mismatches with three coercion modes:

```
use Farzai\JsonSerializer\Engine\DeserializerEngine;
use Farzai\JsonSerializer\Engine\DeserializationContext;
use Farzai\JsonSerializer\Types\TypeCoercionMode;
use Farzai\JsonSerializer\JsonSerializer;

class TypedData {
    public int $id;
    public string $name;
    public float $score;
    public bool $active;
}

// STRICT Mode - No coercion, throw on mismatch
$context = new DeserializationContext(
    typeCoercionMode: TypeCoercionMode::STRICT
);
$deserializer = new DeserializerEngine;
$data = $deserializer->deserializeToClass($json, TypedData::class, $context);
// {"id": "123"} → Throws DeserializationException

// SAFE Mode - Conservative coercion (DEFAULT)
$context = new DeserializationContext(
    typeCoercionMode: TypeCoercionMode::SAFE  // This is the default
);
$deserializer = new DeserializerEngine;
$data = $deserializer->deserializeToClass($json, TypedData::class, $context);
// {"id": "123"} → id = 123 (int)
// {"score": "3.14"} → score = 3.14 (float)
// {"active": "true"} → active = true (bool)
// {"active": 1} → active = true (bool)

// LENIENT Mode - Aggressive coercion
$context = new DeserializationContext(
    typeCoercionMode: TypeCoercionMode::LENIENT
);
$deserializer = new DeserializerEngine;
$data = $deserializer->deserializeToClass($json, TypedData::class, $context);
// {"id": "abc123"} → id = 123 (extracts number)
// {"name": 123} → name = "123" (cast to string)
// {"active": "yes"} → active = true (bool)
// {"active": "no"} → active = false (bool)

// Configure default deserializer for all static methods
$customDeserializer = new DeserializerEngine(
    defaultTypeCoercionMode: TypeCoercionMode::LENIENT
);
JsonSerializer::setDefaultDeserializer($customDeserializer);

// Now all JsonSerializer::decodeToClass() calls use LENIENT mode
$data = JsonSerializer::decodeToClass($json, TypedData::class);
```

#### Coercion Rules

[](#coercion-rules)

**STRICT Mode:**

- No type coercion
- int → float (safe widening)
- Throws exception on any other mismatch

**SAFE Mode (Default):**

- Numeric strings → numbers ("123" → 123)
- Boolean strings → bool ("true" → true, "false" → false)
- 1/0 → boolean
- int → float
- Whole number floats → int (42.0 → 42)

**LENIENT Mode:**

- Any value → string (cast)
- Numeric-like → numbers ("abc123" → 123)
- Truthy/falsy → bool ("yes"/"no", non-empty strings)
- Very permissive conversions

### Custom Type Handlers

[](#custom-type-handlers)

Extend the serializer with custom type handlers for specialized serialization logic:

```
use Farzai\JsonSerializer\Contracts\TypeHandlerInterface;
use Farzai\JsonSerializer\Engine\SerializationContext;
use Farzai\JsonSerializer\JsonSerializer;

// Custom type handler for Money objects
class MoneyTypeHandler implements TypeHandlerInterface
{
    public function supports(mixed $value): bool
    {
        return $value instanceof Money;
    }

    public function serialize(mixed $value, SerializationContext $context): string
    {
        /** @var Money $value */
        return json_encode([
            'amount' => $value->getAmount(),
            'currency' => $value->getCurrency()
        ]);
    }

    public function getPriority(): int
    {
        return 100; // Higher priority = checked first
    }
}

// Register custom handler
$serializer = JsonSerializer::builder()
    ->addTypeHandler(new MoneyTypeHandler())
    ->build();

// Use with custom type
$price = new Money(1999, 'USD');
$json = $serializer->encode($price);
// {"amount":1999,"currency":"USD"}
```

**Use Cases for Custom Type Handlers:**

- Special formatting for value objects (Money, Email, UUID)
- Custom serialization for third-party library objects
- Encryption/decryption during serialization
- Legacy data format compatibility
- Performance optimization for specific types

### PSR-16 Cache Support

[](#psr-16-cache-support)

Improve performance by caching metadata with any PSR-16 compatible cache:

```
use Farzai\JsonSerializer\JsonSerializer;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

// Create PSR-16 cache (using Symfony Cache as example)
$filesystemAdapter = new FilesystemAdapter();
$cache = new Psr16Cache($filesystemAdapter);

// Configure serializer with cache
$serializer = JsonSerializer::builder()
    ->withCache($cache)
    ->build();

// Metadata for classes is now cached
// First serialization: analyzes class metadata
$json1 = $serializer->encode($user);

// Subsequent serializations: uses cached metadata (much faster!)
$json2 = $serializer->encode($anotherUser);
```

**Compatible Cache Libraries:**

- Symfony Cache
- Laravel Cache (via PSR-16 adapter)
- Doctrine Cache
- Any PSR-16 Simple Cache implementation

**Performance Impact:**

- First serialization: ~5-10% slower (cache write)
- Subsequent serializations: ~30-50% faster (cache hit)
- Recommended for applications serializing many instances of the same class

Streaming &amp; Large Files
---------------------------

[](#streaming--large-files)

For processing large JSON files without loading everything into memory, use the streaming API:

### Streaming Deserialization

[](#streaming-deserialization)

```
use Farzai\JsonSerializer\JsonSerializer;

// Stream large JSON file
$stream = JsonSerializer::streamFromFile('large-data.json');

// Iterate over array elements
foreach ($stream->iterateArray() as $item) {
    // Process each item without loading entire array
    echo $item['name'];
}

// Iterate over object fields
foreach ($stream->iterateObject() as [$key, $value]) {
    echo "$key => $value\n";
}
```

### Lazy Iterator

[](#lazy-iterator)

Process large JSON arrays with on-demand deserialization:

```
class User {
    public string $name;
    public string $email;
}

// Lazy load and deserialize array elements
$iterator = JsonSerializer::iterateFile('users.json', User::class);

// Only loads items as you iterate
foreach ($iterator as $user) {
    echo $user->name; // User object created on-demand
}

// Functional operations without loading all data
$adults = $iterator->filter(fn($user) => $user->age >= 18);
$names = $iterator->map(fn($user) => $user->name);
$first10 = $iterator->take(10);
$afterFirst100 = $iterator->skip(100);
```

### Path-based Extraction

[](#path-based-extraction)

Extract specific data without parsing the entire JSON:

```
// Extract single value
$name = JsonSerializer::extractPath('data.json', '.user.name');

// Extract nested field
$email = JsonSerializer::extractPath('data.json', '.user.profile.email');

// Extract array element
$firstItem = JsonSerializer::extractPath('data.json', '.items[0]');

// Extract multiple paths at once
$values = JsonSerializer::extractPaths('data.json', [
    '.user.name',
    '.user.email',
    '.settings.theme'
]);
```

### Memory-Efficient Processing

[](#memory-efficient-processing)

```
// Process 1GB+ JSON file with constant memory usage
$iterator = JsonSerializer::iterateFile('huge-dataset.json');

$count = 0;
$sum = 0;

foreach ($iterator->take(1000) as $item) {
    $count++;
    $sum += $item['value'];
}

echo "Average: " . ($sum / $count);
```

### Generator Serialization

[](#generator-serialization)

Serialize large datasets memory-efficiently using PHP generators:

```
use Farzai\JsonSerializer\JsonSerializer;

// Simple generator - sequential array
function getUsers(): Generator {
    for ($i = 1; $i  $i, 'name' => "User {$i}"];
    }
}

$json = JsonSerializer::encode(getUsers());
// [{"id":1,"name":"User 1"},{"id":2,"name":"User 2"},...]

// Generator yielding objects
function getUserObjects(): Generator {
    for ($i = 1; $i  'MyApp';
    yield 'version' => '1.0.0';
    yield 'debug' => false;
}

$json = JsonSerializer::encode(getConfig());
// {"app_name":"MyApp","version":"1.0.0","debug":false}

// Nested generators
function getCategories(): Generator {
    yield 'electronics' => getProducts('electronics');
    yield 'books' => getProducts('books');
}

function getProducts(string $category): Generator {
    // Fetch products from database one at a time
    foreach ($db->query("SELECT * FROM products WHERE category = ?", [$category]) as $row) {
        yield $row;
    }
}

// Serialize nested generators without loading all data into memory
$json = JsonSerializer::encode(getCategories());
```

**Benefits of Generator Serialization:**

- **Constant Memory Usage**: Only one item in memory at a time
- **Database Streaming**: Fetch and serialize rows without buffering
- **Lazy Evaluation**: Generate data on-demand during serialization
- **Large Datasets**: Process millions of records without memory issues

**When to Use Generators:**

- Serializing database query results (1,000+ rows)
- Processing large CSV files or API responses
- Building JSON from expensive computations
- Any scenario where data doesn't fit comfortably in memory

Performance
-----------

[](#performance)

The library has been benchmarked against native `json_encode/decode` functions using PHPBench. Benchmarks run on PHP 8.1+ with comparable results across versions.

> **Note**: This library prioritizes features and type safety over raw speed. The performance overhead is justified by capabilities like attribute-based configuration, versioning, transformers, and streaming support. For simple use cases where these features aren't needed, native `json_encode/decode` functions are recommended.

### Serialization Performance

[](#serialization-performance)

Data SizeNativeJsonSerializerRatioNotesSmall (&lt;1KB)1.0μs49.3μs~49x slowerOverhead negligible for small data1MB325μs20.3ms~62x slowerRich feature set trade-off5MB1.7ms101.7ms~60x slowerConsistent overhead ratio10MB3.6ms204.6ms~57x slowerScales linearly### Deserialization Performance

[](#deserialization-performance)

Data SizeNativeJsonSerializerRatioNotes1MB942μs936μs**Competitive**Same speed as native!5MB4.9ms4.8ms**Competitive**Same speed as native!10MB9.9ms10.0ms**Competitive**Same speed as native!### Object Hydration Performance

[](#object-hydration-performance)

OperationTimeNotesDecode to Class (1MB)1.1msMinimal overhead for object mappingDecode to Class (5MB)5.5msScales linearly with data sizeNested Objects36μsFast recursive hydration### Memory Usage

[](#memory-usage)

OperationMemory PeakNotesNative (10MB)32.5MBBaselineJsonSerializer (10MB)34.9MB~7% overheadStreaming (10MB)34.9MBConstant memory with file operations### Key Findings

[](#key-findings)

**Deserialization**: JsonSerializer achieves **native-level performance** for deserialization, making it ideal for API consumption and data processing.

**Serialization**: While slower than native for encoding, the overhead is justified by the rich feature set:

- Attribute-based configuration
- Type transformers
- API versioning
- Virtual properties
- Custom naming strategies

**Memory Efficiency**: Memory usage is comparable to native functions with only ~7% overhead for medium to large datasets.

### Running Benchmarks

[](#running-benchmarks)

```
# Run all benchmarks
composer bench

# Run specific benchmark suite
vendor/bin/phpbench run benchmarks/SmallDataBench.php --report=default

# Generate detailed reports
vendor/bin/phpbench run --report=default --store
```

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues and Solutions

[](#common-issues-and-solutions)

#### Memory Limit Errors

[](#memory-limit-errors)

```
// Problem: Fatal error: Allowed memory size exhausted
// Solution 1: Use streaming for large files
$iterator = JsonSerializer::iterateFile('large-file.json', User::class);
foreach ($iterator as $user) {
    // Process one at a time
}

// Solution 2: Increase max depth limit
$serializer = JsonSerializer::builder()
    ->withMaxDepth(100) // Reduce if hitting memory limits
    ->build();
```

#### Type Mismatch Errors

[](#type-mismatch-errors)

```
// Problem: Type mismatch during deserialization
// Solution: Use LENIENT type coercion mode
use Farzai\JsonSerializer\Types\TypeCoercionMode;
use Farzai\JsonSerializer\Engine\DeserializationContext;

$context = new DeserializationContext(
    typeCoercionMode: TypeCoercionMode::LENIENT
);

$deserializer = new DeserializerEngine;
$data = $deserializer->deserializeToClass($json, MyClass::class, $context);
```

#### Circular Reference Errors

[](#circular-reference-errors)

```
// Problem: Circular reference detected
// Solution 1: Fix data structure (recommended)
// Solution 2: Disable detection (use with caution)
$serializer = JsonSerializer::builder()
    ->withCircularReferenceDetection(false)
    ->build();
```

#### Performance Issues

[](#performance-issues)

```
// Problem: Serialization too slow
// Solution 1: Use native functions for simple data
$json = json_encode($simpleArray);

// Solution 2: Enable PSR-16 cache for metadata
$serializer = JsonSerializer::builder()
    ->withCache($psr16Cache)
    ->build();

// Solution 3: Use streaming for large data
JsonSerializer::encodeToFile($data, 'output.json');
```

#### Max Depth Exceeded

[](#max-depth-exceeded)

```
// Problem: Maximum depth exceeded
// Solution: Increase max depth limit
$serializer = JsonSerializer::builder()
    ->withMaxDepth(1000) // Default is 512
    ->build();
```

### Performance Optimization Tips

[](#performance-optimization-tips)

1. **Use PSR-16 Cache**: Cache metadata for classes you serialize frequently
2. **Stream Large Files**: Use `iterateFile()` for files &gt; 100MB
3. **Disable Unused Features**: Turn off circular reference detection if not needed
4. **Use Native for Simple Data**: Reserve this library for complex object mapping
5. **Batch Processing**: Process multiple objects in batches with streaming

### Getting Help

[](#getting-help)

- **GitHub Issues**: [Report bugs or request features](https://github.com/parsilver/json-serializer-php/issues)
- **Documentation**: Check the examples in this README
- **Stack Overflow**: Tag your question with `farzai-json-serializer`

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/parsilver/json-serializer-php/blob/main/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [parsilver](https://github.com/parsilver)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance79

Regular maintenance activity

Popularity1

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 76.7% 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

Unknown

Total

1

Last Release

200d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4928451?v=4)[parsilver](/maintainers/parsilver)[@parsilver](https://github.com/parsilver)

---

Top Contributors

[![parsilver](https://avatars.githubusercontent.com/u/4928451?v=4)](https://github.com/parsilver "parsilver (23 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

phpjsonperformanceserializerstreamingserializationmarshallerencoderdecodertype-safeobject-mappingunmarshaller

###  Code Quality

TestsPest

Static AnalysisPHPStan, Psalm

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/farzai-json-serializer/health.svg)

```
[![Health](https://phpackages.com/badges/farzai-json-serializer/health.svg)](https://phpackages.com/packages/farzai-json-serializer)
```

###  Alternatives

[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts &amp; LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

6115.6k](/packages/sbsaga-toon)[opensoft/simple-serializer

Simple Serializer

1914.2k1](/packages/opensoft-simple-serializer)[suin/json

A Simple wrapper of json\_decode() and json\_encode(). This provides object-oriented interface and exception-based error handing.

1027.6k3](/packages/suin-json)

PHPackages © 2026

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