Symfony JsonStreamer

https://github.com/symfony/json-streamer
Admin
The Symfony JsonStreamer component provides powerful methods to read and write data structures from...
Tokens:7,831
Snippets:35
Trust Score:9.5
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Implementing a Custom Property Metadata Loader

Source: https://context7.com/symfony/json-streamer/llms.txt

Implement `PropertyMetadataLoaderInterface` to customize property mapping. This example renames properties to snake_case in JSON output. Decorate the default loader with your custom implementation.

```php
use Symfony\Component\JsonStreamer\Mapping\PropertyMetadataLoaderInterface;
use Symfony\Component\JsonStreamer\Mapping\PropertyMetadata;
use Symfony\Component\TypeInfo\Type;

// Custom loader that renames all properties to snake_case in JSON
class SnakeCasePropertyMetadataLoader implements PropertyMetadataLoaderInterface
{
    public function __construct(
        private PropertyMetadataLoaderInterface $decorated,
    ) {}

    public function load(string $className, array $options = [], array $context = []): array
    {
        $result = $this->decorated->load($className, $options, $context);
        $renamed = [];

        foreach ($result as $streamedName => $metadata) {
            $snakeName = strtolower(preg_replace('/[A-Z]/', '_$0', lcfirst($streamedName)));
            $renamed[$snakeName] = $metadata->withName($metadata->getName());
        }

        return $renamed;
    }
}
```

```php
// Wire it up in standalone mode:
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\JsonStreamer\Mapping\PropertyMetadataLoader;
use Symfony\Component\TypeInfo\TypeResolver\TypeResolver;

$baseLoader = new PropertyMetadataLoader(TypeResolver::create());
$customLoader = new SnakeCasePropertyMetadataLoader($baseLoader);

// Pass $customLoader when constructing JsonStreamWriter directly (not via ::create())
```

--------------------------------

### Using StreamWriter and StreamReader in a Symfony Controller

Source: https://context7.com/symfony/json-streamer/llms.txt

Inject `StreamWriterInterface` and `StreamReaderInterface` into your controller to stream data. This example demonstrates exporting products using `StreamedResponse`.

```php
use Symfony\Component\JsonStreamer\StreamWriterInterface;
use Symfony\Component\JsonStreamer\StreamReaderInterface;
use Symfony\Component\TypeInfo\Type;

class ProductController
{
    public function __construct(
        private StreamWriterInterface $streamWriter,
        private StreamReaderInterface $streamReader,
    ) {}

    public function export(): \Symfony\Component\HttpFoundation\StreamedResponse
    {
        $products = [/* ... */];
        return new \Symfony\Component\HttpFoundation\StreamedResponse(function () use ($products) {
            foreach ($this->streamWriter->write($products, Type::list(Type::object(\App\Entity\Product::class))) as $chunk) {
                echo $chunk;
            }
        });
    }
}
```

--------------------------------

### Decode JSON Input with JsonStreamReader::read()

Source: https://context7.com/symfony/json-streamer/llms.txt

The `JsonStreamReader::read()` method parses JSON strings or resources into specified PHP types. It supports lazy processing for large files and caches generated reader files. Examples include backed enums, nullable/union types, DateTime parsing with options, and dictionary types.

```php
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

$reader = JsonStreamReader::create();

// Backed enum deserialization
enum Status: string { case Active = 'active'; case Inactive = 'inactive'; }
class Account { public Status $status; public string $name; }

$account = $reader->read('{"status":"active","name":"Bob"}', Type::object(Account::class));
echo $account->status->value; // active

// Nullable and union types
class Profile { public ?string $bio = null; public int|string $id; }
$profile = $reader->read('{"bio":null,"id":"usr_99"}', Type::object(Profile::class));
var_dump($profile->bio);  // NULL
var_dump($profile->id);   // string(6) "usr_99"

// DateTime parsing with options
class Meeting { public \DateTimeImmutable $scheduledAt; }
$meeting = $reader->read(
    '{"scheduledAt":"01/15/2025 09:30"}',
    Type::object(Meeting::class),
    ['date_time_format' => 'm/d/Y H:i']
);
echo $meeting->scheduledAt->format('Y-m-d H:i'); // 2025-01-15 09:30

// Dict (string-keyed map of objects)
$json = '{"alice":{"id":1,"title":"Post A","published":true},"bob":{"id":2,"title":"Post B","published":false}}';
$dict = $reader->read($json, Type::dict(Type::object(Article::class)));
echo $dict['alice']->title; // Post A
```

--------------------------------

### JsonStreamReader::create()

Source: https://context7.com/symfony/json-streamer/llms.txt

Creates a fully configured JsonStreamReader without a DI container. Accepts optional custom transformers and a cache directory. Handles both string input and PHP stream resources.

```APIDOC
## JsonStreamReader::create()

### Description
Creates a fully configured `JsonStreamReader` without a DI container. Accepts optional custom transformers and a cache directory. Handles both string input and PHP stream resources.

### Method
`static JsonStreamReader::create(array $transformers = [], ?string $streamReadersDir = null)`

### Parameters
#### Optional Parameters
- **transformers** (array) - An array of custom transformers to use.
- **streamReadersDir** (string|null) - The directory to cache generated reader files.

### Usage Examples
```php
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

// Create a reader with custom options
$reader = JsonStreamReader::create(
    transformers: [],
    streamReadersDir: '/tmp/json_streamer/read'
);

class Article
{
    public int $id;
    public string $title;
    public bool $published;
}

// Read from a JSON string into a typed object
$json = '{"id":7,"title":"Hello World","published":true}';
/** @var Article $article */
$article = $reader->read($json, Type::object(Article::class));
echo $article->title; // Hello World

// Read a list of objects from a JSON string
$jsonList = '[{"id":1,"title":"First","published":false},{"id":2,"title":"Second","published":true}]';
/** @var Article[] $articles */
$articles = $reader->read($jsonList, Type::list(Type::object(Article::class)));
echo count($articles); // 2

// Read from a stream resource (memory-efficient for large files)
$resource = fopen('/path/to/large.json', 'r');
$article = $reader->read($resource, Type::object(Article::class));
fclose($resource);
```
```

--------------------------------

### Built-in DateTime Transformer with Custom Options

Source: https://context7.com/symfony/json-streamer/llms.txt

Demonstrates the automatic serialization and deserialization of `DateTimeInterface` objects using the built-in transformer. Shows how to control the date-time format and timezone during serialization and deserialization.

```php
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

class Appointment
{
    public \DateTimeImmutable $start;
    public \DateTimeImmutable $end;
    public function __construct()
    {
        $this->start = new \DateTimeImmutable('2025-03-15T09:00:00+00:00');
        $this->end   = new \DateTimeImmutable('2025-03-15T10:30:00+00:00');
    }
}

$writer = JsonStreamWriter::create();

// Default RFC3339 format
echo (string) $writer->write(new Appointment(), Type::object(Appointment::class));
// {"start":"2025-03-15T09:00:00+00:00","end":"2025-03-15T10:30:00+00:00"}

// Custom format + timezone coercion
echo (string) $writer->write(new Appointment(), Type::object(Appointment::class), [
    'date_time_format'   => 'd/m/Y H:i',
    'date_time_timezone' => 'Europe/Paris',
]);
// {"start":"15/03/2025 10:00","end":"15/03/2025 11:30"}

$reader = JsonStreamReader::create();
$appt = $reader->read(
    '{"start":"15/03/2025 09:00","end":"15/03/2025 10:30"}',
    Type::object(Appointment::class),
    ['date_time_format' => 'd/m/Y H:i']
);
echo $appt->start->format('Y-m-d'); // 2025-03-15

```

--------------------------------

### Mark Class for Cache Warming with #[JsonStreamable]

Source: https://context7.com/symfony/json-streamer/llms.txt

The `#[JsonStreamable]` attribute registers a class for pre-generation of stream reader/writer PHP files during cache warmup. Use `asObject` and `asList` flags to control which variants are pre-generated. Without this attribute, files are generated lazily on first use.

```php
use Symfony\Component\JsonStreamer\Attribute\JsonStreamable;

// Pre-generate both object and list stream files at warmup time
#[JsonStreamable(asObject: true, asList: true)]
class Order
{
    public int $id;
    public string $status;
    public float $total;
}

// Only pre-generate object variant (no list)
#[JsonStreamable(asObject: true, asList: false)]
class Invoice
{
    public int $number;
    public \DateTimeImmutable $issuedAt;
}

// In Symfony, tag the class service with json_streamer.streamable
// (handled automatically by StreamablePass compiler pass):
// services.yaml:
//   App\Entity\Order:
//     tags:
//       - { name: json_streamer.streamable, object: true, list: true }
```

--------------------------------

### Create JsonStreamReader Factory

Source: https://context7.com/symfony/json-streamer/llms.txt

Use `JsonStreamReader::create()` to instantiate a reader without a DI container. It accepts custom transformers and a cache directory, and can handle both string input and PHP stream resources.

```php
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

$reader = JsonStreamReader::create(
    transformers: [],
    streamReadersDir: '/tmp/json_streamer/read'
);

class Article
{
    public int $id;
    public string $title;
    public bool $published;
}

// Read from a JSON string
$json = '{"id":7,"title":"Hello World","published":true}';
/** @var Article $article */
$article = $reader->read($json, Type::object(Article::class));
echo $article->title; // Hello World
echo $article->id;    // 7

// Read a list from a string
$jsonList = '[{"id":1,"title":"First","published":false},{"id":2,"title":"Second","published":true}]';
/** @var Article[] $articles */
$articles = $reader->read($jsonList, Type::list(Type::object(Article::class)));
echo count($articles); // 2
echo $articles[1]->title; // Second

// Read from a stream resource (memory-efficient for large files)
$resource = fopen('/path/to/large.json', 'r');
$article = $reader->read($resource, Type::object(Article::class));
fclose($resource);
```

--------------------------------

### #[JsonStreamable]

Source: https://context7.com/symfony/json-streamer/llms.txt

A class-level attribute that registers a class for pre-generation of stream reader/writer PHP files during cache warmup. Without this attribute, files are generated lazily on first use.

```APIDOC
## #[JsonStreamable]

### Description
A class-level attribute that registers a class for pre-generation of stream reader/writer PHP files during cache warmup (in Symfony's kernel warmup phase). Without this attribute, files are generated lazily on first use. Supports `asObject` and `asList` flags to control which variants are pre-generated.

### Usage Examples
```php
use Symfony\Component\JsonStreamer\Attribute\JsonStreamable;

// Pre-generate both object and list stream files at warmup time
#[JsonStreamable(asObject: true, asList: true)]
class Order
{
    public int $id;
    public string $status;
    public float $total;
}

// Only pre-generate object variant (no list)
#[JsonStreamable(asObject: true, asList: false)]
class Invoice
{
    public int $number;
    public \DateTimeImmutable $issuedAt;
}

// In Symfony, tag the class service with json_streamer.streamable
// (handled automatically by StreamablePass compiler pass):
// services.yaml:
//   App\Entity\Order:
//     tags:
//       - { name: json_streamer.streamable, object: true, list: true }
```
```

--------------------------------

### Reusable Property Transformers with PropertyValueTransformerInterface

Source: https://context7.com/symfony/json-streamer/llms.txt

Implement the PropertyValueTransformerInterface to create reusable transformer services. These services can be referenced by their class name in #[ValueTransformer] attributes, promoting code reuse and cleaner attribute definitions.

```php
use Symfony\Component\JsonStreamer\Transformer\PropertyValueTransformerInterface;
use Symfony\Component\JsonStreamer\Attribute\ValueTransformer;
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

// Transformer: PHP bool ↔ JSON "yes"/"no" string
final class BoolToYesNoTransformer implements PropertyValueTransformerInterface
{
    public function transform(mixed $value, array $options = []):
    {
        return $value ? 'yes' : 'no';
    }

    public static function getStreamValueType(): Type
    {
        return Type::string();
    }
}

class Settings
{
    #[ValueTransformer(
        nativeToStream: BoolToYesNoTransformer::class,
        streamToNative: static function (string $v): bool { return $v === 'yes'; }
    )]
    public bool $notifications = true;
}

$writer = JsonStreamWriter::create(transformers: [BoolToYesNoTransformer::class => new BoolToYesNoTransformer()]);
echo (string) $writer->write(new Settings(), Type::object(Settings::class));
// {"notifications":"yes"}

$reader = JsonStreamReader::create(transformers: [BoolToYesNoTransformer::class => new BoolToYesNoTransformer()]);
$s = $reader->read('{\
```

```php
"notifications":"no"}', Type::object(Settings::class));
var_dump($s->notifications); // bool(false)

```

--------------------------------

### Create JsonStreamWriter Standalone

Source: https://context7.com/symfony/json-streamer/llms.txt

Factory method to create a JsonStreamWriter instance without a DI container. Supports custom transformers and a cache directory for writer code.

```php
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\TypeInfo\Type;

$writer = JsonStreamWriter::create(
    transformers: [],                          // optional custom transformers
    streamWritersDir: '/tmp/json_streamer/write' // optional; defaults to sys_get_temp_dir()
);

class Product
{
    public int $id = 42;
    public string $name = 'Widget';
    public float $price = 9.99;
    public bool $inStock = true;
}

$product = new Product();

// write() returns a Traversable&Stringable: stream chunk by chunk or cast to string
$stream = $writer->write($product, Type::object(Product::class));

// Stream to an HTTP response chunk-by-chunk:
foreach ($stream as $chunk) {
    echo $chunk;
}
// Output: {"id":42,"name":"Widget","price":9.99,"inStock":true}

// Or collect as a single string:
$json = (string) $stream;
// $json === '{"id":42,"name":"Widget","price":9.99,"inStock":true}'

// Write a list of objects:
$products = [new Product(), new Product()];
$listStream = $writer->write($products, Type::list(Type::object(Product::class)));
echo (string) $listStream;
// Output: [{"id":42,"name":"Widget","price":9.99,"inStock":true},{"id":42,...}]
```

--------------------------------

### JsonStreamWriter::create()

Source: https://context7.com/symfony/json-streamer/llms.txt

Creates a standalone JsonStreamWriter instance without a DI container. It accepts optional custom transformers and a cache directory path. Built-in transformers for date/time types are automatically registered.

```APIDOC
## JsonStreamWriter::create() - Standalone writer factory

### Description
Creates a fully configured `JsonStreamWriter` instance without a DI container. Accepts an optional map of custom transformers and an optional cache directory path. Built-in transformers for `DateTimeInterface`, `DateInterval`, and `DateTimeZone` are registered automatically.

### Method
```php
public static function create(array $transformers = [], ?string $streamWritersDir = null)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\TypeInfo\Type;

$writer = JsonStreamWriter::create(
    transformers: [],                          // optional custom transformers
    streamWritersDir: '/tmp/json_streamer/write' // optional; defaults to sys_get_temp_dir()
);

class Product
{
    public int $id = 42;
    public string $name = 'Widget';
    public float $price = 9.99;
    public bool $inStock = true;
}

$product = new Product();

// write() returns a Traversable&Stringable: stream chunk by chunk or cast to string
$stream = $writer->write($product, Type::object(Product::class));

// Stream to an HTTP response chunk-by-chunk:
foreach ($stream as $chunk) {
    echo $chunk;
}
// Output: {"id":42,"name":"Widget","price":9.99,"inStock":true}

// Or collect as a single string:
$json = (string) $stream;
// $json === '{"id":42,"name":"Widget","price":9.99,"inStock":true}'

// Write a list of objects:
$products = [new Product(), new Product()];
$listStream = $writer->write($products, Type::list(Type::object(Product::class)));
echo (string) $listStream;
// Output: [{"id":42,"name":"Widget","price":9.99,"inStock":true},{"id":42,...}]
```

### Response
#### Success Response (200)
Returns a `JsonStreamWriter` instance.

#### Response Example
None provided.
```

--------------------------------

### Custom Value Object Transformer for Money

Source: https://context7.com/symfony/json-streamer/llms.txt

Define a custom transformer for a `Money` value object, enabling its serialization to and deserialization from a string format like "1000 USD". Register this transformer with `JsonStreamWriter` and `JsonStreamReader` to handle `Money` objects transparently.

```php
use Symfony\Component\JsonStreamer\Transformer\ValueObjectTransformerInterface;
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;
use Symfony\Component\TypeInfo\Type\BuiltinType;

// Value object
final class Money
{
    public function __construct(
        public readonly int $amount,
        public readonly string $currency,
    ) {}
}

// Transformer: Money ↔ "1000 USD" string
final class MoneyTransformer implements ValueObjectTransformerInterface
{
    public function transform(object $object, array $options = []): string
    {
        return $object->amount.' '.$object->currency;
    }

    public function reverseTransform(int|float|string|bool|null $scalar, array $options = []): Money
    {
        [$amount, $currency] = explode(' ', (string) $scalar, 2);
        return new Money((int) $amount, $currency);
    }

    public static function getStreamValueType(): BuiltinType { return Type::string(); }
    public static function getValueObjectClassName(): string  { return Money::class; }
}

class Invoice
{
    public Money $total;
    public ?Money $discount = null;
    public function __construct() { $this->total = new Money(4999, 'EUR'); }
}

$transformers = [Money::class => new MoneyTransformer()];

$writer = JsonStreamWriter::create(transformers: $transformers);
echo (string) $writer->write(new Invoice(), Type::object(Invoice::class));
// {"total":"4999 EUR","discount":null}

$reader = JsonStreamReader::create(transformers: $transformers);
$inv = $reader->read('{"total":"2500 USD","discount":"100 USD"}', Type::object(Invoice::class));
echo $inv->total->amount;    // 2500
echo $inv->total->currency;  // USD
echo $inv->discount->amount; // 100

```

--------------------------------

### Registering StreamablePass and TransformerPass in Symfony Bundle

Source: https://context7.com/symfony/json-streamer/llms.txt

Add these compiler passes in your Symfony Bundle's `build()` method to integrate JSON Streamer services. Ensure your entities are tagged correctly in `services.yaml`.

```php
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Bundle\Bundle;
use Symfony\Component\JsonStreamer\DependencyInjection\StreamablePass;
use Symfony\Component\JsonStreamer\DependencyInjection\TransformerPass;

class AppBundle extends Bundle
{
    public function build(ContainerBuilder $container): void
    {
        $container->addCompilerPass(new StreamablePass());
        $container->addCompilerPass(new TransformerPass());
    }
}
```

```yaml
# services.yaml — register streamable models:
# App\Entity\Product:
#   tags:
#     - { name: json_streamer.streamable, object: true, list: true }

# services.yaml — register a custom value object transformer:
# App\Transformer\MoneyTransformer:
#   tags:
#     - { name: json_streamer.value_object_transformer }

# services.yaml — register a property value transformer:
# App\Transformer\BoolToYesNoTransformer:
#   tags:
#     - { name: json_streamer.property_value_transformer }
```

--------------------------------

### JsonStreamReader::read()

Source: https://context7.com/symfony/json-streamer/llms.txt

Parses a JSON string or resource into the specified PHP type. When passed a resource, the reader operates lazily, enabling efficient processing of arbitrarily large files. The generated reader PHP file is cached on first invocation.

```APIDOC
## JsonStreamReader::read()

### Description
Parses a JSON string or resource into the specified PHP type. When passed a resource, the reader operates lazily, enabling efficient processing of arbitrarily large files. The generated reader PHP file is cached on first invocation.

### Method
`JsonStreamReader::read(string|resource $json, Type $type, array $options = [])`

### Parameters
#### Path Parameters
- **json** (string|resource) - The JSON string or stream resource to parse.
- **type** (Type) - The target PHP type to decode into.
- **options** (array) - Optional decoding options. See examples for usage.

### Usage Examples
```php
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

$reader = JsonStreamReader::create();

// Backed enum deserialization
enum Status: string { case Active = 'active'; case Inactive = 'inactive'; }
class Account { public Status $status; public string $name; }

$account = $reader->read('{"status":"active","name":"Bob"}', Type::object(Account::class));
echo $account->status->value; // active

// Nullable and union types
class Profile { public ?string $bio = null; public int|string $id; }
$profile = $reader->read('{"bio":null,"id":"usr_99"}', Type::object(Profile::class));
var_dump($profile->bio);  // NULL
var_dump($profile->id);   // string(6) "usr_99"

// DateTime parsing with options
class Meeting { public \DateTimeImmutable $scheduledAt; }
$meeting = $reader->read(
    '{"scheduledAt":"01/15/2025 09:30"}',
    Type::object(Meeting::class),
    ['date_time_format' => 'm/d/Y H:i']
);
echo $meeting->scheduledAt->format('Y-m-d H:i'); // 2025-01-15 09:30

// Dict (string-keyed map of objects)
$json = '{"alice":{"id":1,"title":"Post A","published":true},"bob":{"id":2,"title":"Post B","published":false}}';
$dict = $reader->read($json, Type::dict(Type::object(Article::class)));
echo $dict['alice']->title; // Post A
```
```

--------------------------------

### Per-Property Value Transformation with #[ValueTransformer]

Source: https://context7.com/symfony/json-streamer/llms.txt

The #[ValueTransformer] attribute allows defining custom callable logic for converting property values between PHP native types and their JSON stream representations. This supports inline callables, static method references, and service IDs.

```php
use Symfony\Component\JsonStreamer\Attribute\ValueTransformer;
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

class Report
{
    // Inline callables: store as int, stream as string representation
    #[ValueTransformer(
        nativeToStream: 'strval',       // int → string when writing
        streamToNative: 'intval',       // string → int when reading
    )]
    public int $count = 42;

    // Static method references
    #[ValueTransformer(
        nativeToStream: [self::class, 'encodeRange'],
        streamToNative: [self::class, 'decodeRange'],
    )]
    public array $range = [1, 100];

    // Closure-based (defined at construction via custom loader in DI)
    #[ValueTransformer(nativeToStream: 'strtoupper', streamToNative: 'strtolower')]
    public string $tag = 'monthly';

    public static function encodeRange(array $r): string { return $r[0].'..'.$r[1]; }
    public static function decodeRange(string $r): array { return array_map('intval', explode('..', $r)); }
}

$writer = JsonStreamWriter::create();
echo (string) $writer->write(new Report(), Type::object(Report::class));
// {"count":"42","range":"1..100","tag":"MONTHLY"}

$reader = JsonStreamReader::create();
$report = $reader->read('{\
```

```php
"count":"99","range":"5..50","tag":"WEEKLY"}', Type::object(Report::class));
var_dump($report->count); // int(99)
var_dump($report->range); // array(2) { [0]=> int(5), [1]=> int(50) }
echo $report->tag;        // weekly

```

--------------------------------

### Encode Data to JSON Stream

Source: https://context7.com/symfony/json-streamer/llms.txt

Primary method to convert PHP values to a lazy JSON stream. Ideal for streaming HTTP responses without buffering. Supports various types and options like null property inclusion and date formatting.

```php
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\TypeInfo\Type;

$writer = JsonStreamWriter::create();

// Scalar types
$intStream = $writer->write(123, Type::int());
echo (string) $intStream; // 123

// Null-safe nullable object
class User { public ?string $email = null; public string $login = 'alice'; }
$stream = $writer->write(new User(), Type::object(User::class));
echo (string) $stream; // {"email":null,"login":"alice"}

// With options: include_null_properties controls null output (default: true)
$writer2 = JsonStreamWriter::create();
$stream2 = $writer2->write(new User(), Type::object(User::class), [
    'include_null_properties' => false,
]);
echo (string) $stream2; // {"login":"alice"}

// DateTime with custom format and timezone
class Event {
    public \DateTimeImmutable $startsAt;
    public function __construct() { $this->startsAt = new \DateTimeImmutable('2024-06-01 12:00:00', new \DateTimeZone('UTC')); }
}
$stream3 = $writer->write(new Event(), Type::object(Event::class), [
    'date_time_format' => 'Y-m-d',
    'date_time_timezone' => 'America/New_York',
]);
echo (string) $stream3; // {"startsAt":"2024-05-31"}
```

--------------------------------

### Customize JSON Property Name with #[StreamedName]

Source: https://context7.com/symfony/json-streamer/llms.txt

Use the #[StreamedName] attribute to map PHP property names to different JSON keys during serialization and deserialization. This is useful for adhering to external API specifications or for using reserved keywords in JSON.

```php
use Symfony\Component\JsonStreamer\Attribute\StreamedName;
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\JsonStreamer\JsonStreamReader;
use Symfony\Component\TypeInfo\Type;

class ApiResponse
{
    #[StreamedName('@context')]
    public string $context = 'https://schema.org';

    #[StreamedName('given_name')]
    public string $firstName = 'Alice';

    #[StreamedName('family_name')]
    public string $lastName = 'Smith';

    // No attribute: JSON key matches property name
    public int $id = 1;
}

$writer = JsonStreamWriter::create();
$json = (string) $writer->write(new ApiResponse(), Type::object(ApiResponse::class));
echo $json;
// {"@context":"https:\/\/schema.org","given_name":"Alice","family_name":"Smith","id":1}

$reader = JsonStreamReader::create();
$obj = $reader->read('{\
```

```php
"@context":"https:\/\/schema.org","given_name":"Bob","family_name":"Jones","id":2}', Type::object(ApiResponse::class));
echo $obj->firstName;  // Bob
echo $obj->context;    // https://schema.org

```

--------------------------------

### JsonStreamWriter::write()

Source: https://context7.com/symfony/json-streamer/llms.txt

Encodes any PHP value to a lazy JSON stream according to the given Type. It returns a Traversable&Stringable that yields chunks progressively, making it suitable for streaming HTTP responses without buffering the entire output.

```APIDOC
## JsonStreamWriter::write() - Encode data to a JSON stream

### Description
The primary write method. Converts any PHP value to a lazy JSON stream according to the given `Type`. Returns a `Traversable&Stringable` whose chunks are yielded progressively—ideal for streaming HTTP responses without buffering the full output.

### Method
```php
public function write(mixed $value, Type $type, array $options = []): Traversable&Stringable
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
use Symfony\Component\JsonStreamer\JsonStreamWriter;
use Symfony\Component\TypeInfo\Type;

$writer = JsonStreamWriter::create();

// Scalar types
$intStream = $writer->write(123, Type::int());
echo (string) $intStream; // 123

// Null-safe nullable object
class User { public ?string $email = null; public string $login = 'alice'; }
$stream = $writer->write(new User(), Type::object(User::class));
echo (string) $stream; // {"email":null,"login":"alice"}

// With options: include_null_properties controls null output (default: true)
$writer2 = JsonStreamWriter::create();
$stream2 = $writer2->write(new User(), Type::object(User::class), [
    'include_null_properties' => false,
]);
echo (string) $stream2; // {"login":"alice"}

// DateTime with custom format and timezone
class Event {
    public \DateTimeImmutable $startsAt;
    public function __construct() { $this->startsAt = new \DateTimeImmutable('2024-06-01 12:00:00', new \DateTimeZone('UTC')); }
}
$stream3 = $writer->write(new Event(), Type::object(Event::class), [
    'date_time_format' => 'Y-m-d',
    'date_time_timezone' => 'America/New_York',
]);
echo (string) $stream3; // {"startsAt":"2024-05-31"}
```

### Response
#### Success Response (200)
Returns a `Traversable&Stringable` that yields JSON stream chunks.

#### Response Example
None provided.
```
Tokens:
Raw