- How do I install and use jms/serializer in a Laravel application?
- Install it with composer require jms/serializer and build a serializer with SerializerBuilder::create()->build(). In Laravel, register the serializer as a singleton in a service provider and inject it where needed. You can then call serialize($object, 'json') or deserialize($payload, User::class, 'json'). There is no official Laravel wrapper, so metadata paths and caching are configured manually.
- Is jms/serializer compatible with Laravel 10 and Laravel 11?
- jms/serializer is framework agnostic, so it can be used with Laravel 10 and 11 as long as your PHP version satisfies its Composer constraints. The supported 3.x line targets modern PHP 8 releases, while 1.x and 2.x are no longer supported. Check the exact PHP requirement of the jms/serializer version you install and run your test suite after upgrading. Laravel integration is manual, not via an official Laravel package.
- Can jms/serializer serialize Laravel Eloquent models?
- Yes, Eloquent models are PHP objects, so jms/serializer can serialize them, but it does not automatically honor Laravel features such as $hidden, $visible, $appends, or API Resource transformations. Loaded relationships can expose large graphs or circular references, so use exclusion policies, groups, or DTOs to control output. Many teams serialize dedicated DTOs instead of Eloquent models for stable API contracts.
- How do I handle circular references in jms/serializer?
- Use setCircularReferenceHandler() on SerializerBuilder to return an identifier instead of recursing, for example the model primary key. You can also set a circular reference limit and combine it with exclusion strategies or serialization groups to avoid serializing both sides of a relationship. For Laravel APIs, select only needed columns and relations before serialization to keep graphs small.
- How does jms/serializer support API versioning with serialization groups?
- Add PHP 8 attributes such as #[Groups(['v1'])] to properties or methods and serialize with a context that sets the active groups. Different API versions can use different group names so fields are included or excluded per version. Keep group definitions explicit and test each version to prevent accidental data exposure.
- Should I use PHP attributes, annotations, YAML, or XML for jms/serializer metadata?
- Version 3.x supports PHP 8 attributes by default, which is the best choice for new Laravel code because metadata stays next to the class. Annotations are legacy, while YAML and XML metadata require configuring the appropriate driver and, for YAML, the symfony/yaml dependency. Choose one approach consistently and cache metadata in production.
- Is jms/serializer a replacement for Laravel API Resources or league/fractal?
- They solve different problems: Laravel API Resources and Fractal focus on transforming outgoing API responses, while jms/serializer handles both serialization and deserialization with metadata, groups, versioning, and XML support. If you only need simple JSON responses, native Laravel resources are usually lighter. jms/serializer is more useful when you need to hydrate objects from JSON or XML or serialize complex graphs.
- How do I serialize Carbon dates or custom value objects with jms/serializer?
- jms/serializer includes handlers for DateTimeInterface, so Carbon instances are generally handled as dates, but you should configure the expected format with metadata or a custom handler. For UUIDs or domain value objects, create a custom handler and register it on SerializerBuilder, or use handler attributes on the property. Test timezone and format behavior because it affects API compatibility.
- What should I consider for jms/serializer performance in production Laravel APIs?
- Metadata parsing and reflection add overhead compared with plain json_encode(), so enable a metadata cache such as a file cache or PSR-6 cache in production. Warm the cache during deployment and avoid serializing deeply loaded Eloquent graphs or unnecessary relations. Benchmark your critical endpoints and use groups or DTOs to keep payloads focused.
- How do I test jms/serializer serialization and deserialization in Laravel?
- Write PHPUnit or Pest tests that assert the serialized JSON or XML for representative objects, including excluded fields and each serialization group. Add round-trip tests that deserialize the payload back into a DTO or model and compare the result. Clear or isolate the metadata cache in CI and test edge cases such as dates, nulls, and circular references.