Download the PHP package tcds-io/php-jackson-symfony without Composer

PHP Jackson for Symfony

Symfony integration for tcds-io/php-jackson, a type-safe object mapper inspired by Jackson (Java).

This package lets you:

• Inject typed objects and collections directly into Symfony controllers
• Deserialize from JSON body, query params, form data, and route params
• Automatically serialize your return values back to JSON using PHP-Jackson
• Opt into request and response mapping with PHP attributes

Installation

Enable the bundle if Symfony Flex did not add it automatically:

No configuration file is needed for the attribute-based setup. Create one only when you need global mappers or custom params:

How it works

1. Mark request DTO parameters with #[JacksonInject].
2. Mark return values that should be serialized with #[JacksonResponse].
3. The bundle inspects your method parameter types and PHPDoc generics.
4. It builds those objects from:
   • Route params ({id})
   • Query / form data
   • JSON body
5. Your return value is serialized using PHP-Jackson.

Controller-based injection & response

Invokable controllers

Symfony routes usually point to controller services. For compact endpoints, use an invokable controller:

Response status and headers

• #[JacksonInject] on a parameter forces php-jackson to deserialize the request payload into that type, even when the type is not registered in mappers or has been opted out via reader: null.
• #[JacksonResponse(status: 201)] on a method serializes the return value via php-jackson and wraps it in a Symfony Response with the given status and headers. status defaults to 200.

Extending Jackson configuration

The attribute-based API is the default path for request and response mapping, but the bundle also has a central configuration file for application-wide behavior. Use it to add global serialization rules and inject custom params into mapped objects.

Create config

Create the configuration file when you need global mappers or custom params:

Add global mappers

Global mappers tell Jackson to always handle a type in requests and responses without adding attributes to every controller method. They are useful when a DTO is part of your app-wide API contract, or when you want to define custom read/write behavior once instead of repeating it at each endpoint.

With a configured mapper, Jackson can read and write that type without #[JacksonInject] or #[JacksonResponse]:

Responses serialized this way use status 200 and do not support custom headers. Use #[JacksonResponse] when an endpoint needs a different status code or response headers.

Inject custom params

Custom params let you add request-scoped values that do not come from the URL, query string, form data, or JSON body. This is useful for authenticated user IDs, tenant IDs, locale, feature flags, or any value you want available while Jackson builds a request object.

Those values are merged into the data used to build Jackson objects, so a DTO can receive them like any other constructor field:

Error handling

If parsing fails, php-jackson-symfony converts a php-jackson UnableToParseValue exception into a 400 Bad Request response by default:

Set errors.request when your API needs a different response shape or status code. The handler receives an UnableToParseValue exception and must return a Symfony Response.

The UnableToParseValue exception exposes:

• $e->getMessage() - human-readable description of the failure
• $e->expected - list of accepted values or types
• $e->given - the type or value that was received

Development

End-to-end integration tests run a real Symfony app:

Related packages

• Core mapper: https://github.com/tcds-io/php-jackson
• Laravel integration: https://github.com/tcds-io/php-jackson-laravel
• Guzzle integration: https://github.com/tcds-io/php-jackson-guzzle