Symfony Serializer

https://github.com/symfony/serializer
Admin
Symfony Serializer is a component for serializing and deserializing complex data structures and...
Tokens:143,109
Snippets:856
Trust Score:9.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Point class implementing NormalizableInterface and DenormalizableInterface with usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/normalizer-interfaces.md

Shows a Point class that implements the required interfaces, with normalize() returning an array and denormalize() setting properties from data. The example then creates a Serializer with CustomNormalizer and JsonEncoder, and deserializes JSON into a Point object.

```php
class Point implements NormalizableInterface, DenormalizableInterface
{
    public function __construct(public int $x, public int $y) {}

    public function normalize(NormalizerInterface $normalizer, ?string $format = null, array $context = []): array|string|int|float|bool|\ArrayObject|null
    {
        return ['x' => $this->x, 'y' => $this->y];
    }

    public function denormalize(DenormalizerInterface $denormalizer, array|string|int|float|bool $data, ?string $format = null, array $context = []): void
    {
        $this->x = $data['x'];
        $this->y = $data['y'];
    }
}

$serializer = new Serializer([new CustomNormalizer()], [new JsonEncoder()]);
$point = $serializer->deserialize('{"x":1,"y":2}', Point::class, 'json');
```

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

### deserialize() usage examples

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Shows typical usage of deserialize() for a single object, an array of objects, and error collection with DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS. The error-collection example catches PartialDenormalizationException to access partially populated data and per-field errors.

```php
$dto = $serializer->deserialize('{"name":"Ada","role":"admin"}', User::class, 'json');
// $dto instanceof User

$users = $serializer->deserialize('[{"name":"Ada"},{"name":"Bob"}]', User::class.'[]', 'json');
// array of User

// Collect every error instead of stopping at the first one
try {
    $serializer->deserialize('{"email":"not-an-email"}', User::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
    ]);
} catch (PartialDenormalizationException $e) {
    $partial = $e->getData();                       // partially populated User
    foreach ($e->getNotNormalizableValueErrors() as $error) { /* ... */ }
}
```

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

### DateTimeNormalizer usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/data-normalizers.md

Shows how to instantiate DateTimeNormalizer with custom format and timezone, normalize a DateTimeImmutable, and handle denormalization errors with NotNormalizableValueException.

```php
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

$normalizer = new DateTimeNormalizer([
    DateTimeNormalizer::FORMAT_KEY => 'Y-m-d H:i:s',
    DateTimeNormalizer::TIMEZONE_KEY => 'Europe/Paris',
]);

$json = $normalizer->normalize(new \DateTimeImmutable('2026-01-15 10:00:00'));
// '2026-01-15 10:00:00'

// Error handling
try {
    $normalizer->denormalize('not a date', \DateTimeImmutable::class, null);
} catch (\Symfony\Component\Serializer\Exception\NotNormalizableValueException $e) {
    // path/expected types available through getPath()/getExpectedTypes()
}
```

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

### DateIntervalNormalizer usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/data-normalizers.md

Shows how to denormalize an ISO 8601 interval string into a \DateInterval and then normalize it back to the same string. The output is 'P1Y2M3DT4H5M6S'.

```php
$normalizer = new DateIntervalNormalizer();
$interval = $normalizer->denormalize('P1Y2M3DT4H5M6S', \DateInterval::class);
echo $normalizer->normalize($interval); // 'P1Y2M3DT4H5M6S'
```

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

### DateTimeNormalizerContextBuilder usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Demonstrates how to use a concrete context builder to construct a context array for normalization, with immutability and merging.

```APIDOC
## DateTimeNormalizerContextBuilder usage example

### Description
Demonstrates how to use a concrete context builder to construct a context array for normalization, with immutability and merging.

### Example
```php
use Symfony\Component\Serializer\Context\Normalizer\DateTimeNormalizerContextBuilder;

$builder = (new DateTimeNormalizerContextBuilder())
    ->withFormat('Y-m-d')
    ->withTimezone('UTC', force: true);

$context = $builder->toArray(); // ['datetime_format' => 'Y-m-d', 'datetime_timezone' => 'UTC', 'datetime_force_timezone' => true]

// Add more options
$more = $builder->withCast('int')->toArray();
```
```

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

### ObjectNormalizer::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/object-normalizers.md

Creates an ObjectNormalizer instance. Throws a LogicException if the symfony/property-access component is not installed.

```APIDOC
## ObjectNormalizer::__construct

### Description
Creates an ObjectNormalizer instance. Throws a LogicException if the symfony/property-access component is not installed.

### Method
__construct

### Signature
```php
public function __construct(
    ?ClassMetadataFactoryInterface $classMetadataFactory = null,
    ?NameConverterInterface $nameConverter = null,
    ?PropertyAccessorInterface $propertyAccessor = null,
    ?PropertyTypeExtractorInterface $propertyTypeExtractor = null,
    ?ClassDiscriminatorResolverInterface $classDiscriminatorResolver = null,
    ?callable $objectClassResolver = null,
    array $defaultContext = [],
    ?PropertyInfoExtractorInterface $propertyInfoExtractor = null,
)
```

### Parameters
- **classMetadataFactory** (?ClassMetadataFactoryInterface) - Optional - Class metadata factory.
- **nameConverter** (?NameConverterInterface) - Optional - Name converter.
- **propertyAccessor** (?PropertyAccessorInterface) - Optional - Property accessor. Defaults to `PropertyAccess::createPropertyAccessor()`.
- **propertyTypeExtractor** (?PropertyTypeExtractorInterface) - Optional - Property type extractor.
- **classDiscriminatorResolver** (?ClassDiscriminatorResolverInterface) - Optional - Class discriminator resolver.
- **objectClassResolver** (?callable) - Optional - Object class resolver. Defaults to `static fn ($class) => \is_object($class) ? $class::class : $class`.
- **defaultContext** (array) - Optional - Default context.
- **propertyInfoExtractor** (?PropertyInfoExtractorInterface) - Optional - Property info extractor. Defaults to `ReflectionExtractor`.

### Exceptions
- **LogicException** - Thrown when the `symfony/property-access` component is not installed.
```

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

### ProblemNormalizer usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/error-normalizers.md

Creates a ProblemNormalizer with debug enabled and normalizes a FlattenException created from a throwable. Output includes type, title, status, detail, class, and trace fields.

```php
use Symfony\Component\ErrorHandler\Exception\FlattenException;

$normalizer = new ProblemNormalizer(debug: true);
$result = $normalizer->normalize(FlattenException::createFromThrowable($exception), 'json');
// {type, title, status, detail, class, trace}
```

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

### BackedEnumNormalizer usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/data-normalizers.md

Shows denormalizing a string to a BackedEnum instance and using the ALLOW_INVALID_VALUES context option for lenient handling of invalid values. In lenient mode, invalid input returns null instead of throwing an exception.

```php
enum Role: string { case Admin = 'admin'; case User = 'user'; }

$normalizer = new BackedEnumNormalizer();
$role = $normalizer->denormalize('admin', Role::class);   // Role::Admin

// lenient mode
$role = $normalizer->denormalize('unknown', Role::class, null,
    [BackedEnumNormalizer::ALLOW_INVALID_VALUES => true]); // null
```

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

### CsvEncoder usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/xml-csv-yaml-encoders.md

Demonstrates encoding an array of associative arrays into CSV and decoding it back. Nested keys using dot notation are flattened during encoding and rebuilt during decoding.

```php
use Symfony\Component\Serializer\Encoder\CsvEncoder;

$encoder = new CsvEncoder();
$csv = $encoder->encode([
    ['user.name' => 'Ada', 'user.role' => 'admin'],
    ['user.name' => 'Bob', 'user.role' => 'user'],
], 'csv');

$rows = $encoder->decode($csv, 'csv');
// [['user' => ['name' => 'Ada', 'role' => 'admin']], ['user' => ['name' => 'Bob', 'role' => 'user']]]

```

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

### FormErrorNormalizer output JSON example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/error-normalizers.md

Example output of FormErrorNormalizer::normalize() for a submitted and invalid form. Contains title, type, code (400), errors array, and children structure. Context options TITLE, TYPE, and CODE (= status_code) customize the output.

```json
{
  "title": "Validation Failed",
  "type": "https://symfony.com/errors/form",
  "code": 400,
  "errors": [ { "message": "…", "cause": null } ],
  "children": { "fieldName": { "errors": [ … ], "children": { … } } }
}
```

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

### XmlEncoder usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/xml-csv-yaml-encoders.md

Shows how to instantiate XmlEncoder with a custom root node name and encode an array to XML. The output is a string with the root element 'order' and attributes prefixed with '@'. Decoding the XML back returns the original array structure.

```php
use Symfony\Component\Serializer\Encoder\XmlEncoder;

$encoder = new XmlEncoder(['xml_root_node_name' => 'order']);
$xml = $encoder->encode([
    '@id' => 42,
    'status' => 'paid',
    'lines' => ['item' => [['sku' => 'A1', 'qty' => 2]]],
], 'xml');

// <order id="42"><status>paid</status><lines><item><sku>A1</sku><qty>2</qty></item></lines></order>
$back = $encoder->decode($xml, 'xml');
```

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

### YamlEncoder::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/xml-csv-yaml-encoders.md

Constructor for the YamlEncoder. Accepts optional custom Dumper and Parser instances, and a default context array. Throws RuntimeException if the symfony/yaml component is not installed.

```APIDOC
## YamlEncoder::__construct

### Description
Constructor for the YamlEncoder. Accepts optional custom Dumper and Parser instances, and a default context array. Throws RuntimeException if the symfony/yaml component is not installed.

### Method
Constructor

### Signature
`public function __construct(?Dumper $dumper = null, ?Parser $parser = null, array $defaultContext = [])`

### Parameters
- **$dumper** (Dumper|null) - Optional - Custom Yaml\Dumper instance.
- **$parser** (Parser|null) - Optional - Custom Yaml\Parser instance.
- **$defaultContext** (array) - Optional - Default context options. Defaults to `[]`.

### Notes
- Requires the `symfony/yaml` component; without it, throws `RuntimeException`.
- `yaml_indentation` is constructor-only: sets the dumper's indentation and is removed from the context afterwards.
- Default context: `yaml_inline => 0`, `yaml_indent => 0`, `yaml_flags => 0`.
```

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

### MaxDepth usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/attributes.md

Apply #[MaxDepth(1)] to a property and enable the feature via AbstractObjectNormalizer::ENABLE_MAX_DEPTH during normalization.

```php
use Symfony\Component\Serializer\Attribute\MaxDepth;
use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;

class Article
{
    #[MaxDepth(1)]
    public array $comments = [];
}
$serializer->normalize($article, null, [AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true]);

```

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

### Context attribute usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/attributes.md

Shows how to apply the Context attribute to a property to override the normalization context for a DateTimeImmutable field, using DateTimeNormalizer::FORMAT_KEY to set the date format.

```php
use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Event
{
    #[Context([DateTimeNormalizer::FORMAT_KEY => 'Y-m-d'])]
    public \DateTimeImmutable $startsAt;
}
```

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

### ArrayDenormalizer usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/normalizer-interfaces.md

Shows how to use ArrayDenormalizer with ObjectNormalizer and JsonEncoder to deserialize a JSON array into an array of User objects. Requires the nested denormalizer to be set; otherwise a BadMethodCallException is thrown.

```php
$serializer = new Serializer(
    [new ArrayDenormalizer(), new ObjectNormalizer()],
    [new JsonEncoder()]
);
/** @var User[] $users */
$users = $serializer->deserialize('[{"id":1},{"id":2}]', 'App\Model\User[]', 'json');
```

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

### shutdown() usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

After calling shutdown, normalizers hold only a WeakReference to the serializer.

```php
$serializer->shutdown(); // afterwards, normalizers hold only a WeakReference to $serializer
```

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

### DiscriminatorMap usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/attributes.md

Demonstrates using DiscriminatorMap to deserialize polymorphic classes based on a type property. The mapping maps type values to class names; deserializing with type 'dog' returns a Dog instance.

```php
use Symfony\Component\Serializer\Attribute\DiscriminatorMap;

#[DiscriminatorMap(typeProperty: 'type', mapping: [
    'cat' => Cat::class,
    'dog' => Dog::class,
])]
abstract class Animal {}

class Cat extends Animal {}
class Dog extends Animal {}

$animal = $serializer->deserialize('{"type":"dog","name":"Rex"}', Animal::class, 'json'); // Dog
```

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

### Groups attribute usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/attributes.md

Shows applying Groups to class properties. Normalizing with groups ['default'] only includes the title property, excluding internalNote.

```php
use Symfony\Component\Serializer\Attribute\Groups;

class Book
{
    #[Groups(['default', 'admin'])]
    public string $title;

    #[Groups(['admin'])]
    public string $internalNote;
}
// $serializer->normalize($book, null, ['groups' => ['default']]) → only 'title'
```

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

### JsonEncoder usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/encoders.md

Shows how to instantiate a Serializer with an ObjectNormalizer and JsonEncoder, then serialize and deserialize an array. The deserialized result is an associative array due to the default JsonDecode::ASSOCIATIVE context.

```php
use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\Serializer\Serializer;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

$serializer = new Serializer([new ObjectNormalizer()], [new JsonEncoder()]);
$json = $serializer->serialize(['a' => ['b' => 1]], 'json');
$data = $serializer->deserialize($json, 'array', 'json'); // ['a' => ['b' => 1]]
```

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

### DateTimeNormalizerContextBuilder usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Builds a context array for DateTimeNormalizer with format, timezone, and force timezone options. withFormat() and withTimezone() return new instances; toArray() produces the context array. The builder is immutable, so adding more options via withCast() creates a new array.

```php
use Symfony\Component\Serializer\Context\Normalizer\DateTimeNormalizerContextBuilder;

$builder = (new DateTimeNormalizerContextBuilder())
    ->withFormat('Y-m-d')
    ->withTimezone('UTC', force: true);

$context = $builder->toArray(); // ['datetime_format' => 'Y-m-d', 'datetime_timezone' => 'UTC', 'datetime_force_timezone' => true]

// Add more options
$more = $builder->withCast('int')->toArray();
```

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

### Using UnwrappingDenormalizer with context builder

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/normalizer-interfaces.md

Shows how to deserialize a nested JSON value using UnwrappingDenormalizer with UnwrappingDenormalizerContextBuilder. The context key 'unwrap_path' is set via withUnwrapPath('[wrapper][user]'). The serializer is configured with UnwrappingDenormalizer and ObjectNormalizer, and uses JsonEncoder. The example deserializes a JSON payload containing a nested user object into a User class.

```php
use Symfony\Component\Serializer\Context\Normalizer\UnwrappingDenormalizerContextBuilder;

$serializer = new Serializer([new UnwrappingDenormalizer(), new ObjectNormalizer()], [new JsonEncoder()]);

$payload = '{"wrapper":{"user":{"name":"Ada"}}}';
$ctx = (new UnwrappingDenormalizerContextBuilder())->withUnwrapPath('[wrapper][user]')->toArray();
$user = $serializer->deserialize($payload, User::class, 'json', $ctx);
```

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

### XmlEncoderContextBuilder usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Shows how to use XmlEncoderContextBuilder to configure XML serialization options such as root node name and formatted output. The builder's toArray() method returns the context array to pass as the third argument to serialize().

```php
use Symfony\Component\Serializer\Context\Encoder\XmlEncoderContextBuilder;
use Symfony\Component\Serializer\Encoder\XmlEncoder;

$serializer->serialize($data, 'xml', (new XmlEncoderContextBuilder())
    ->withRootNodeName('orders')
    ->withFormatOutput(true)
    ->toArray());
```

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

### ConstraintViolationListNormalizer normalize() output shape

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/error-normalizers.md

Example JSON output from normalize() for a validation failure. Shows the RFC 7807 structure with violations array, including propertyPath, title, template, parameters, type, and payload fields.

```json
{
  "type": "https://symfony.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "name: This value should not be blank.",
  "instance": "…",
  "violations": [
    {
      "propertyPath": "name",
      "title": "This value should not be blank.",
      "template": "This value should not be blank.",
      "parameters": { "{{ value }}": "\"\"" },
      "type": "urn:uuid:…",
      "payload": {}
    }
  ]
}
```

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

### DebugCommand class skeleton for debug:serializer

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/bundle-integration.md

Defines the console command `debug:serializer` using the `#[AsCommand]` attribute. The constructor injects `ClassMetadataFactoryInterface`. Running `bin/console debug:serializer 'App\Entity\Dummy'` prints a table of Property → Options (groups, serialized names, contexts, discriminator info). Returns `Command::FAILURE` with a `Class "…" was not found.` error for unknown classes, `Command::SUCCESS` otherwise.

```php
#[AsCommand(name: 'debug:serializer', description: 'Display serialization information for classes')]
class DebugCommand extends Command
{
    public function __construct(private readonly ClassMetadataFactoryInterface $serializer)
}
```

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

### Using PropertyNormalizer with visibility context

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/object-normalizers.md

Shows how to instantiate a Serializer with PropertyNormalizer and JsonEncoder. The first serialize call restricts output to public properties via NORMALIZE_VISIBILITY => NORMALIZE_PUBLIC. The second call uses the default (all visibilities) to include private and protected properties.

```php
$serializer = new Serializer([new PropertyNormalizer()], [new JsonEncoder()]);

// Only public properties are serialized
$json = $serializer->serialize($entity, 'json', [
    PropertyNormalizer::NORMALIZE_VISIBILITY => PropertyNormalizer::NORMALIZE_PUBLIC,
]);

// Private/protected included (default)
$json = $serializer->serialize($entity, 'json');
```

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

### Serialize and denormalize with ObjectNormalizer

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/object-normalizers.md

Shows how to use ObjectNormalizer with a Serializer to serialize an object to JSON and denormalize into an existing object using OBJECT_TO_POPULATE. The output shows the serialized JSON with the DateTimeImmutable formatted as ISO 8601.

```php
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\Serializer\Serializer;

$serializer = new Serializer([new ObjectNormalizer()], [new JsonEncoder()]);

$event = new Meeting('Release planning', new \DateTimeImmutable('2026-01-15 10:00'));
echo $serializer->serialize($event, 'json');
// {"title":"Release planning","startsAt":"2026-01-15T10:00:00+00:00"}

// Denormalization into an existing object (OBJECT_TO_POPULATE)
$update = ['title' => 'Release planning (moved)'];
$serializer->deserialize(json_encode($update), Meeting::class, 'json', [
    ObjectNormalizer::OBJECT_TO_POPULATE => $event,
]);
```

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

### AbstractObjectNormalizer constructor

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/abstract-normalizers.md

Constructor accepting optional metadata factory, name converter, property type extractor, discriminator resolver, object class resolver, and default context. The defaultContext's MAX_DEPTH_HANDLER must be callable or an InvalidArgumentException is thrown.

```php
public function __construct(
    ?ClassMetadataFactoryInterface $classMetadataFactory = null,
    ?NameConverterInterface $nameConverter = null,
    private ?PropertyTypeExtractorInterface $propertyTypeExtractor = null,
    ?ClassDiscriminatorResolverInterface $classDiscriminatorResolver = null,
    ?callable $objectClassResolver = null,
    array $defaultContext = [],
)
```

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

### AbstractNormalizer constructor signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/abstract-normalizers.md

Constructor accepts optional class metadata factory, name converter, and default context array. Throws InvalidArgumentException for non-callable callbacks or circular reference handler.

```php
public function __construct(
    protected ?ClassMetadataFactoryInterface $classMetadataFactory = null,
    protected ?NameConverterInterface $nameConverter = null,
    array $defaultContext = [],
)
```

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

### MetadataAwareNameConverter usage example

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/name-converters.md

Shows how to use MetadataAwareNameConverter with ObjectNormalizer. Creates a ClassMetadataFactory with AttributeLoader, then instantiates the converter with the factory. Normalizing a User object with SerializedName('user_name') produces ['user_name' => …].

```php
use Symfony\Component\Serializer\Attribute\SerializedName;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader;
use Symfony\Component\Serializer\NameConverter\MetadataAwareNameConverter;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

class User
{
    #[SerializedName('user_name')]
    public string $name;
}

$factory = new ClassMetadataFactory(new AttributeLoader());
$normalizer = new ObjectNormalizer(
    classMetadataFactory: $factory,
    nameConverter: new MetadataAwareNameConverter($factory),
);
$data = $normalizer->normalize($user); // ['user_name' => …]
```

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

### AbstractNormalizerContextBuilder::withObjectToPopulate()

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Sets the object_to_populate context option for normalizers. Use this to specify an object to populate during denormalization.

```APIDOC
## `withObjectToPopulate(?object $objectToPopulate): static`

### Description
Sets the `object_to_populate` context key.

### Method
`withObjectToPopulate`

### Parameters
- `$objectToPopulate` (?object) - Optional - The object to populate.

### Returns
`static` - The builder instance for chaining.
```

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

### Basic usage with ReflectionExtractor

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/extractor.md

Creates an ObjectPropertyListExtractor with a ReflectionExtractor to list properties of an entity, e.g. ['id', 'name', 'email'].

```php
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
use Symfony\Component\Serializer\Extractor\ObjectPropertyListExtractor;

$extractor = new ObjectPropertyListExtractor(new ReflectionExtractor());
$properties = $extractor->getProperties($entity); // e.g. ['id', 'name', 'email']
```

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

### Serializer bundle configuration in config/packages/serializer.yaml

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/configuration.md

Configure the Symfony Serializer bundle via YAML. The `enabled` key defaults to true and can disable the extension. `enable_attributes` controls runtime attribute discovery; disabling it still leaves compile-time autoconfiguration active. `name_converter`, `circular_reference_handler`, and `max_depth_handler` accept service ids, with the latter two bound into normalizers' `$defaultContext`. `default_context` merges arbitrary keys into every serializer default context. `mapping.paths` adds extra XML/YAML mapping paths; nonexistent paths throw a `\RuntimeException`. `named_serializers` allows additional named serializer configurations, but `default` is reserved.

```yaml
# config/packages/serializer.yaml
framework:
    serializer:
        enabled: true                      # default: true (canBeDisabled)
        enable_attributes: true            # runtime (and compile-time) attribute discovery
        name_converter: App\Serializer\MyNameConverter   # service id
        circular_reference_handler: App\Serializer\my_circular_handler   # service id of a callable
        max_depth_handler: App\Serializer\my_max_depth_handler
        default_context:
            enable_max_depth: true         # arbitrary keys → merged into every serializer default context
            skip_null_values: true
        mapping:
            paths: ['%kernel.project_dir%/config/serializer']   # extra XML/YAML mapping paths
        named_serializers:
            compact:                       # any name except 'default'
                name_converter: ~
                default_context: { skip_null_values: true }
                include_built_in_normalizers: true
                include_built_in_encoders: true

```

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

### ContextBuilderTrait

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Provides the core implementation for context builders, including the `with` method for setting individual context keys with immutability.

```APIDOC
## ContextBuilderTrait

### Description
Provides the core implementation for context builders, including the `with` method for setting individual context keys with immutability.

### Methods
- `with(string $key, mixed $value): static` - Sets a context key to a value and returns a new instance (immutable).
- `withContext(ContextBuilderInterface|array $context): static` - Merges the given context (another builder or array) into the current builder and returns a new instance.
- `toArray(): array` - Returns the accumulated context as an array.

### Source
`Context/ContextBuilderTrait.php:10`
```

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

### AbstractNormalizer::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/abstract-normalizers.md

Constructor for the AbstractNormalizer class. Initializes the normalizer with optional class metadata factory, name converter, and default context.

```APIDOC
## AbstractNormalizer::__construct

### Description
Constructor for the AbstractNormalizer class. Initializes the normalizer with optional class metadata factory, name converter, and default context.

### Method
Constructor

### Signature
```php
public function __construct(
    protected ?ClassMetadataFactoryInterface $classMetadataFactory = null,
    protected ?NameConverterInterface $nameConverter = null,
    array $defaultContext = [],
)
```

### Parameters
- **$classMetadataFactory** (?ClassMetadataFactoryInterface) - Optional - Provides groups/serialized-name metadata
- **$nameConverter** (?NameConverterInterface) - Optional - Renames attributes during (de)normalization
- **$defaultContext** (array<string, mixed>) - Optional - Merged over the built-in defaults

### Exceptions
- **InvalidArgumentException** - When a CALLBACKS entry is not callable or when CIRCULAR_REFERENCE_HANDLER is not callable
```

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

### ContextBuilderTrait implementation

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Provides the shared implementation for context builders. with() returns a new instance (immutability), withContext() merges another builder's array, and toArray() returns the accumulated array.

```php
trait ContextBuilderTrait
{
    protected function with(string $key, mixed $value): static;
    public function withContext(ContextBuilderInterface|array $context): static;
    public function toArray(): array;
}
```

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

### Normalize Uuid to base58

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/data-normalizers.md

Shows how to use UidNormalizer to normalize a Uuid instance to a base58 string by passing the NORMALIZATION_FORMAT_KEY context option. Requires the symfony/uid component.

```php
use Symfony\Component\Uid\Uuid;
$normalizer = new UidNormalizer();
echo $normalizer->normalize(Uuid::v4(), null, [UidNormalizer::NORMALIZATION_FORMAT_KEY => 'base58']);
```

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

### ObjectToPopulateTrait: extractObjectToPopulate method

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/normalizer-interfaces.md

Defines the trait method that extracts AbstractNormalizer::OBJECT_TO_POPULATE from the context, returning the object only when it is an instance of the given class. Used by AbstractNormalizer and CustomNormalizer.

```php
trait ObjectToPopulateTrait
{
    protected function extractObjectToPopulate(string $class, array $context, ?string $key = null): ?object;
}
```

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

### LoaderChain class definition

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/mapping.md

Calls every loader in order. The optional $mappedClasses map lets the chain skip loaders that declared they only map certain classes. LoaderChainAwareInterface loaders get prepareLoading()/finalizeLoading() hooks. Throws MappingException when a loader does not implement LoaderInterface or a mapped-class key has no matching loader.

```php
class LoaderChain implements LoaderInterface
{
    public function __construct(
        private readonly array $loaders,
        private readonly array $mappedClasses = [],     // loader index => [class => true]
    )
    public function loadClassMetadata(ClassMetadataInterface $metadata): bool
    public function getLoaders(): array
}
```

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

### Catch Multiple Serializer Exceptions with Aggregate try-catch

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/errors.md

Use this pattern to handle deserialization failures by catching ExtraAttributesException, MissingConstructorArgumentsException, and NotNormalizableValueException together. The example passes 'allow_extra_attributes' => false to trigger ExtraAttributesException for unknown keys. Each exception provides specific methods: getExtraAttributes() for unknown keys, getMissingConstructorArguments() and getClass() for missing constructor args, and getPath(), getExpectedTypes(), getCurrentType() for normalization errors.

```php
use Symfony\Component\Serializer\Exception\ExtraAttributesException;
use Symfony\Component\Serializer\Exception\MissingConstructorArgumentsException;
use Symfony\Component\Serializer\Exception\NotNormalizableValueException;

try {
    $serializer->deserialize($payload, User::class, 'json', [
        'allow_extra_attributes' => false,
    ]);
} catch (ExtraAttributesException $e) {
    // $e->getExtraAttributes() → list of unknown keys
} catch (MissingConstructorArgumentsException $e) {
    // $e->getMissingConstructorArguments(), $e->getClass()
} catch (NotNormalizableValueException $e) {
    // $e->getPath(), $e->getExpectedTypes(), $e->getCurrentType()
}
```

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

### AbstractObjectNormalizer::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/abstract-normalizers.md

Constructor for the AbstractObjectNormalizer class. Initializes the normalizer with optional metadata factory, name converter, property type extractor, discriminator resolver, object class resolver, and default context.

```APIDOC
## Constructor: `AbstractObjectNormalizer::__construct`

### Description
Initializes the AbstractObjectNormalizer with optional dependencies and default context.

### Method
`__construct`

### Signature
```php
public function __construct(
    ?ClassMetadataFactoryInterface $classMetadataFactory = null,
    ?NameConverterInterface $nameConverter = null,
    private ?PropertyTypeExtractorInterface $propertyTypeExtractor = null,
    ?ClassDiscriminatorResolverInterface $classDiscriminatorResolver = null,
    ?callable $objectClassResolver = null,
    array $defaultContext = [],
)
```

### Parameters
- `$classMetadataFactory` (?ClassMetadataFactoryInterface) - Optional - Metadata (groups, names, discriminator maps)
- `$nameConverter` (?NameConverterInterface) - Optional - Attribute renaming
- `$propertyTypeExtractor` (?PropertyTypeExtractorInterface) - Optional - PropertyInfo type extraction for type enforcement
- `$classDiscriminatorResolver` (?ClassDiscriminatorResolverInterface) - Optional - Discriminator map resolution; defaults to `ClassDiscriminatorFromClassMetadata` when a metadata factory is given
- `$objectClassResolver` (?callable) - Optional - Callable resolving class names for objects (defaults to `get_class`)
- `$defaultContext` (array<string, mixed>) - Optional - Merged into defaults; `MAX_DEPTH_HANDLER` must be callable or `InvalidArgumentException`

### Notes
- The `$propertyTypeExtractor` parameter is private and promoted.
- The `$defaultContext` parameter must have a callable `MAX_DEPTH_HANDLER` if provided, otherwise an `InvalidArgumentException` is thrown.
```

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

### supportsEncoding() and supportsDecoding() method signatures

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Delegate to the chains; return false instead of throwing when no encoder/decoder matches. Sources: Serializer.php:438 and Serializer.php:443.

```php
public function supportsEncoding(string $format, array $context = []): bool
public function supportsDecoding(string $format, array $context = []): bool
```

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

### encode() method signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Delegates to the internal ChainEncoder. Throws RuntimeException when no encoder supports the format. Source: Serializer.php:428.

```php
final public function encode(mixed $data, string $format, array $context = []): string
```

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

### AbstractNormalizerContextBuilder::withRequireAllProperties()

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Sets the require_all_properties context option for normalizers. Use this to require all properties to be present.

```APIDOC
## `withRequireAllProperties(?bool $requireAllProperties = true): static`

### Description
Sets the `require_all_properties` context key.

### Method
`withRequireAllProperties`

### Parameters
- `$requireAllProperties` (?bool) - Optional - Whether to require all properties. Defaults to `true`.

### Returns
`static` - The builder instance for chaining.
```

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

### Serializer constructor signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Constructor accepting ordered normalizers, encoders, default context, and an optional shared cache key.

```php
public function __construct(
    private array $normalizers = [],
    private array $encoders = [],
    private array $defaultContext = [],
    private ?string $sharedCacheKey = null,
)
```

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

### Extra context constants

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/abstract-normalizers.md

Constants that define context keys used by the AbstractObjectNormalizer to control normalization and denormalization behavior.

```APIDOC
## Extra context constants

### Description
These constants are used as context keys to control the behavior of the normalizer.

### Constants
| Constant | Value | Meaning |
|----------|-------|---------|
| `ENABLE_MAX_DEPTH` | `'enable_max_depth'` | Respect `#[MaxDepth]` metadata |
| `DEPTH_KEY_PATTERN` | `'depth_%s::%s'` | How depth is tracked in the context |
| `DISABLE_TYPE_ENFORCEMENT` | `'disable_type_enforcement'` | True disables denormalization type checks |
| `ENABLE_TYPE_CONVERSION` | `'enable_type_conversion'` | Convert scalar strings to expected types; enabled by default for XML and CSV, computed once and propagated to child contexts |
| `SKIP_NULL_VALUES` | `'skip_null_values'` | Drop `null` fields during normalization |
| `SKIP_UNINITIALIZED_VALUES` | `'skip_uninitialized_values'` | Skip uninitialized typed properties; default `true` |
| `MAX_DEPTH_HANDLER` | `'max_depth_handler'` | Callable invoked when max depth is reached (args: `$attributeValue, $object, $attributeName, $format, $context`); without it, the attribute is skipped |
| `EXCLUDE_FROM_CACHE_KEY` | `'exclude_from_cache_key'` | Context keys not relevant to the attribute cache key |
| `DEEP_OBJECT_TO_POPULATE` | `'deep_object_to_populate'` | Also populate existing objects on nested attributes (only useful with root `OBJECT_TO_POPULATE`) |
| `PRESERVE_EMPTY_OBJECTS` | `'preserve_empty_objects'` | Keep empty objects as objects (`{}`) instead of lists (`[]`) |
```

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

### UidNormalizer::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/data-normalizers.md

Constructor for the UidNormalizer class. Accepts an optional default context array that can specify the default normalization format.

```APIDOC
## `UidNormalizer::__construct`

### Description
Constructor for the UidNormalizer class. Accepts an optional default context array that can specify the default normalization format.

### Method
Constructor

### Signature
`public function __construct(array $defaultContext = [])`

### Parameters
- **$defaultContext** (array) - Optional - Default context array. Defaults to `NORMALIZATION_FORMAT_CANONICAL`.
```

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

### UnwrappingDenormalizer class declaration

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/normalizer-interfaces.md

Declares the UnwrappingDenormalizer class implementing DenormalizerInterface and SerializerAwareInterface. It uses SerializerAwareTrait and defines the UNWRAP_PATH constant. The constructor accepts an optional PropertyAccessorInterface. getSupportedTypes returns ['*' => false]. supportsDenormalization() returns true only when 'unwrap_path' is in context and the 'unwrapped' marker is not set. If the path is not readable on data, denormalize returns null. If the injected serializer is not a denormalizer, it throws LogicException('Cannot unwrap path because the injected serializer is not a denormalizer.').

```php
final class UnwrappingDenormalizer implements DenormalizerInterface, SerializerAwareInterface
{
    use SerializerAwareTrait;
    public const UNWRAP_PATH = 'unwrap_path';

    public function __construct(?PropertyAccessorInterface $propertyAccessor = null)
    public function getSupportedTypes(?string $format): array;   // ['*' => false]
    public function denormalize(mixed $data, string $type, ?string $format = null, array $context = []): mixed;
    public function supportsDenormalization(mixed $data, string $type, ?string $format = null, array $context = []): bool;
}
```

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

### serialize() method signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Final method that serializes data to a string in the given format with optional context.

```php
final public function serialize(mixed $data, string $format, array $context = []): string
```

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

### FileLoader abstract class definition

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/mapping.md

Abstract base for file-based loaders. Throws MappingException when the mapping file does not exist or is not readable.

```php
abstract class FileLoader implements LoaderInterface
{
    public function __construct(
        protected string $file,
    )
}
```

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

### deserialize() method signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Signature for the Serializer::deserialize() method. Accepts serialized data, target type (supports 'Foo[]' for arrays), format, and optional context. Returns the denormalized object or mixed. Throws UnsupportedFormatException if no decoder supports the format.

```php
final public function deserialize(mixed $data, string $type, string $format, array $context = []): mixed
```

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

### AbstractObjectNormalizerContextBuilder::withDeepObjectToPopulate()

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Sets the deep_object_to_populate context option for object normalizers. Use this to enable deep population of objects.

```APIDOC
## `withDeepObjectToPopulate(?bool $deepObjectToPopulate): static`

### Description
Sets the `deep_object_to_populate` context key.

### Method
`withDeepObjectToPopulate`

### Parameters
- `$deepObjectToPopulate` (?bool) - Optional - Whether to enable deep object population.

### Returns
`static` - The builder instance for chaining.
```

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

### ExceptionInterface marker interface

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/errors.md

Marker base interface that every component exception implements. Extends \Throwable.

```php
interface ExceptionInterface extends \Throwable {}
```

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

### AbstractNormalizerContextBuilder::withCallbacks()

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/context-builders.md

Sets the callbacks context option for normalizers. Use this to register callbacks for serialization.

```APIDOC
## `withCallbacks(?array $callbacks): static`

### Description
Sets the `callbacks` context key.

### Method
`withCallbacks`

### Parameters
- `$callbacks` (?array) - Optional - The callbacks to register.

### Returns
`static` - The builder instance for chaining.
```

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

### PropertyNormalizer::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/object-normalizers.md

Constructor for the PropertyNormalizer class. Initializes the normalizer with optional dependencies and default context, setting default visibility to public, protected, and private properties.

```APIDOC
## PropertyNormalizer::__construct

### Description
Initializes a new PropertyNormalizer instance with optional class metadata factory, name converter, property type extractor, class discriminator resolver, object class resolver, and default context.

### Method
Constructor

### Signature
```php
public function __construct(
    ?ClassMetadataFactoryInterface $classMetadataFactory = null,
    ?NameConverterInterface $nameConverter = null,
    ?PropertyTypeExtractorInterface $propertyTypeExtractor = null,
    ?ClassDiscriminatorResolverInterface $classDiscriminatorResolver = null,
    ?callable $objectClassResolver = null,
    array $defaultContext = [],
)
```

### Parameters
- **$classMetadataFactory** (?ClassMetadataFactoryInterface) - Optional - Class metadata factory.
- **$nameConverter** (?NameConverterInterface) - Optional - Name converter.
- **$propertyTypeExtractor** (?PropertyTypeExtractorInterface) - Optional - Property type extractor.
- **$classDiscriminatorResolver** (?ClassDiscriminatorResolverInterface) - Optional - Class discriminator resolver.
- **$objectClassResolver** (?callable) - Optional - Object class resolver.
- **$defaultContext** (array) - Optional - Default context options.

### Notes
Sets default visibility to `NORMALIZE_PUBLIC | NORMALIZE_PROTECTED | NORMALIZE_PRIVATE` when not provided.
```

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

### decode() method signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Delegates to the internal ChainDecoder. Throws RuntimeException when no decoder supports the format. Source: Serializer.php:433.

```php
final public function decode(string $data, string $format, array $context = []): mixed
```

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

### GetSetMethodNormalizer class signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/object-normalizers.md

Defines the final class extending AbstractObjectNormalizer with methods for supported types and normalization/denormalization checks. The getSupportedTypes method returns ['object' => true].

```php
final class GetSetMethodNormalizer extends AbstractObjectNormalizer
{
    public function getSupportedTypes(?string $format): array;   // ['object' => true]
    public function supportsNormalization(mixed $data, ?string $format = null, array $context = []): bool;
    public function supportsDenormalization(mixed $data, string $type, ?string $format = null, array $context = []): bool;
}
```

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

### SerializerCacheWarmer class skeleton

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/bundle-integration.md

Defines `SerializerCacheWarmer` extending `AbstractPhpFileCacheWarmer`. It accepts an array of loaders and a PHP array file path. The `doWarmUp` method warms the metadata cache by loading metadata of every class mapped by `XmlFileLoader`/`YamlFileLoader`/`AttributeLoader` (loaders exposing `getMappedClasses()`; `LoaderChain` is unwrapped). Requires `$buildDir` (else returns `false`), tolerates autoload failures (`ignoreAutoloadException`).

```php
final class SerializerCacheWarmer extends AbstractPhpFileCacheWarmer
{
    public function __construct(
        private array $loaders,
        string $phpArrayFile,
    )
    protected function doWarmUp(string $cacheDir, ArrayAdapter $arrayAdapter, ?string $buildDir = null): bool
}
```

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

### Ticket class with getter/setter and serializer usage

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/object-normalizers.md

Shows a Ticket class with getTitle/setTitle methods and how to use GetSetMethodNormalizer with a Serializer to deserialize and serialize JSON. Deserialization calls setTitle('Bug #42') and serialization outputs {"title":"Bug #42"}.

```php
class Ticket
{
    private string $title;

    public function getTitle(): string { return $this->title; }
    public function setTitle(string $title): void { $this->title = $title; }
}

$serializer = new Serializer([new GetSetMethodNormalizer()], [new JsonEncoder()]);
$ticket = $serializer->deserialize('{"title":"Bug #42"}', Ticket::class, 'json');
// calls setTitle('Bug #42')
echo $serializer->serialize($ticket, 'json'); // {"title":"Bug #42"}
```

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

### Serializer::__construct

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Creates a new Serializer instance with the given normalizers, encoders, default context, and optional shared cache key. The normalizers and encoders are validated and injected with the serializer if they implement the appropriate interfaces.

```APIDOC
## Serializer::__construct

### Description
Creates a new Serializer instance with the given normalizers, encoders, default context, and optional shared cache key. The normalizers and encoders are validated and injected with the serializer if they implement the appropriate interfaces.

### Method
Constructor

### Signature
```php
public function __construct(
    private array $normalizers = [],
    private array $encoders = [],
    private array $defaultContext = [],
    private ?string $sharedCacheKey = null,
)
```

### Parameters
- **$normalizers** (array<NormalizerInterface|DenormalizerInterface>) - Optional - Default: `[]` - Ordered list of normalizers; the first one supporting the data is used
- **$encoders** (array<EncoderInterface|DecoderInterface>) - Optional - Default: `[]` - Ordered list of encoders/decoders; split internally into a `ChainEncoder` and a `ChainDecoder`
- **$defaultContext** (array<string, mixed>) - Optional - Default: `[]` - Default context merged under per-call contexts
- **$sharedCacheKey** (?string) - Optional - Default: `null` - Serializers created with the same key and normalizers of the same classes share the cached "which normalizer supports which type" resolution

### Behavior
- Every normalizer implementing `SerializerAwareInterface`, `DenormalizerAwareInterface` or `NormalizerAwareInterface` gets the serializer injected through the corresponding `set*()` method.
- A normalizer that implements neither `NormalizerInterface` nor `DenormalizerInterface` → `InvalidArgumentException`.
- An encoder that implements neither `EncoderInterface` nor `DecoderInterface` → `InvalidArgumentException`.
- When `$sharedCacheKey` is set, it is suffixed with `:xxh128-hash` of the list of normalizer class names.
- Encoders are partitioned: `EncoderInterface` instances feed the `ChainEncoder`, `DecoderInterface` instances feed the `ChainDecoder`.
```

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

### supportsDenormalization() method signature

Source: https://github.com/symfony/serializer/blob/8.2/_autodocs/api-reference/serializer.md

Returns true for built-in scalar types (int, bool, float, string) or when a registered denormalizer supports the type. Source: Serializer.php:284.

```php
public function supportsDenormalization(mixed $data, string $type, ?string $format = null, array $context = []): bool
```
Tokens:
Raw