JMS Serializer

JMS Serializer is a mature PHP library dedicated to converting complex object graphs into JSON or XML and back again, handling circular references, inheritance, and nested collections gracefully. It exposes a rich metadata layer — configurable via PHP attributes, annotations, XML, or YAML — that lets developers control exactly how properties are named, grouped, excluded, and versioned during (de)serialization, making it a common choice for building versioned public APIs.

Beyond basic conversion, the library ships with built-in support for common PHP types like DateTime and DateInterval, integrates with Doctrine ORM for lazy-loaded entity handling, and provides an extensible handler system for custom type conversions. Its exclusion-strategy and group system make it well suited for APIs that need to expose different views of the same data model to different consumers.

What You Get

• A SerializerBuilder for constructing a configured serializer instance with sane defaults
• Metadata-driven mapping via PHP attributes, Doctrine-style annotations, XML, or YAML
• Exclusion strategies and versioning support for building backward-compatible, evolving APIs
• Built-in handlers for common PHP types (DateTime, DateInterval) and Doctrine collections
• Support for grouping fields into serialization “views” for different API consumers
• Extensible event system for hooking into the (de)serialization lifecycle

Common Use Cases

• Serializing Doctrine entities into JSON API responses without exposing internal fields
• Building versioned REST APIs where older clients receive a stable subset of properties
• Converting between JSON/XML payloads and rich domain objects in message-driven systems
• Generating consistent API output across a Symfony application via bundle integration

Under The Hood

Architecture The library centers on a Serializer facade built via SerializerBuilder, which wires together a GraphNavigator that walks object graphs, per-type Visitor implementations (JsonSerializationVisitor, JsonDeserializationVisitor, XML equivalents) that render/parse the wire format, and a Metadata layer that describes how each class’s properties map to serialized output. Property-level behavior (naming, exclusion, versioning, type hints) is driven by metadata loaded from attributes/annotations/XML/YAML via jms/metadata, decoupling the mapping rules from the visitor/navigator traversal logic.

Tech Stack Pure PHP 7.4/8.x library with no runtime framework dependency; it composes with doctrine/instantiator and doctrine/lexer for object construction and expression parsing, and optionally with Doctrine ORM/Collections, Symfony components (validator, form, dependency-injection, uid), and Twig for framework integration. Tooling includes PHPUnit for tests, PHPStan for static analysis, PHP-CS-Fixer/PHPCS for style, and PHPBench for performance benchmarking.

Code Quality The tests/ directory mirrors src/ closely with 302 test files covering serializer builders, handlers, visitors, and exclusion strategies, indicating thorough unit coverage. The codebase uses PHPStan for static analysis and enforces a coding standard via doctrine/coding-standard, and the public API is organized into clearly named interfaces (SerializerInterface, GraphNavigatorInterface) that separate contracts from implementations.

API Design The primary entry point (SerializerBuilder::create()->build()) offers a fluent, discoverable configuration API, and common tasks (serialize/deserialize) require only one or two method calls. Sphinx-based documentation in doc/ (usage, cookbook, handlers, reference) is extensive, though the breadth of configuration options (metadata formats, exclusion strategies, versioning) does add a moderate learning curve for newcomers.