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

PHP-Jackson

A lightweight, flexible object serializer for PHP, inspired by Jackson.

It provides strong typing, JSON ↔ object mapping, generics support, array/object shapes, custom type mappers, and detailed error tracing.

📚 Contents

• Overview
• Integrations
  • Laravel ↗
  • Symfony ↗
  • Guzzle ↗
• Installation
• Basic Usage
• Deserializing from JSON
• Merging Additional Data (readValueWith)
• Serializing Objects
• Generic Types (list<t> map<k, v> shapes)
  • List Example
  • Map Example
  • Array Shape Example
  • Object Shape Example
• Renaming JSON keys with #[JsonProperty]
• Custom Type Mappers
  • Using Custom Mappers with External Context
  • Pinning a Mapper on the Class with #[JsonMapper]
• Date Handling
• Error Handling
• Development
• Summary

Overview

Main components:

• JsonObjectMapper — handles JSON strings at the boundary.
• ArrayObjectMapper — handles associative arrays at the boundary.
• Type Mappers — custom readers/writers for specific classes.
• Generic Types — support for list<T>, map<K,V>, shapes, etc.
• Date Handling — built-in support for DateTime and Carbon.
• Error Reporting — typed exceptions with full trace paths.

🚀 Installation

🧩 Integrations

PHP Jackson offers first-class integrations for popular PHP frameworks and tools. Each integration extends the core mapper with framework-specific features for a smoother development experience.

Official Plugins:

• Laravel ↗ — controller injection, JSON responses, request error handling, and Eloquent casts
• Symfony ↗ — controller argument resolvers, JSON responses, and configurable request error handling
• Guzzle ↗ — typed HTTP client with request DTO mapping and async response parsing

🔧 Basic Usage

Reading JSON into typed objects

Equivalent array version:

📥 Deserializing from JSON

The resulting object matches:

➕ Merging Additional Data (readValueWith)

Merging data is useful when the incoming payload does not contain all required values and those values must be completed from another source:

📤 Serializing Objects

Array output:

JSON output:

📚 Generic Types (list<T>, map<K,V>, shapes)

The generic() and shape() helper functions are loaded by Composer through php-better-generics.

List example

Using generic():

Map example

Array Shape Example

Produces:

Object Shape Example

Produces a stdClass:

🏷️ Renaming JSON keys with #[JsonProperty]

PHP-Jackson maps JSON keys to PHP names 1:1 by default. When the wire format uses a different naming convention (snake_case, kebab-case, etc.), pin the JSON key on the constructor parameter (or property) with #[JsonProperty]:

The attribute is honored on both directions:

Error traces and the expected payload on UnableToParseValue use the wire key — the one users will recognize from the JSON they are sending — not the PHP identifier.

🧩 Custom Type Mappers

Custom mappers are useful when object construction depends on complex logic or external data:

This allows:

to become:

and serialize back into:

Using Custom Mappers with External Context

Mapper closures can receive any of the named arguments used internally by PHP-Jackson:

Use only the parameters you need; ReflectionFunction::call() binds them by name.

Pinning a Mapper on the Class with #[JsonMapper]

If a class always wants the same custom (de)serialization, declare it once on the class itself instead of registering it on every mapper instance:

The reader and writer accept any of:

• a class string of an implementation of Reader / Writer (instance is built with a no-arg constructor),
• a class string of StaticReader / StaticWriter (no instance — the static read / write is called),
• a class string of any class with a matching __invoke (treated as a MapperClosure),
• an instance of Reader / Writer (PHP 8.1 new in attribute initializers),
• a Closure matching MapperClosure, when constructing JsonMapper programmatically (PHP attribute literals can't carry closures).

Resolution order on every read/write:

1. #[JsonMapper] attribute on the target class — declaration site, wins
2. typeMappers constructor argument
3. default reader/writer

That is, an explicit class-level mapper cannot be silently overridden by mapper-instance config — the class itself is the canonical source.

🕒 Date Handling

PHP-Jackson provides built-in support for:

• DateTime
• DateTimeImmutable
• Carbon
• CarbonImmutable
• DateTimeInterface

Dates are serialized and deserialized using ISO-8601 strings:

❗ Error Handling

When parsing fails, the library throws:

UnableToParseValue

Properties:

Example message:

This makes debugging extremely easy.

🔧 Development

✅ Summary

You can:

• Read JSON → typed objects via JsonObjectMapper
• Read arrays → typed objects via ArrayObjectMapper
• Merge missing fields using readValueWith
• Write objects → JSON/arrays via writeValue
• Use generics (list<T>, map<K,V>, shapes)
• Rename wire keys per field with #[JsonProperty('snake_case')]
• Register custom mappers for any class via typeMappers or pin them on the class itself with #[JsonMapper(reader: …, writer: …)]
• Rely on strong error tracing with full path information