- What is json-mapper/json-mapper used for?
- json-mapper/json-mapper hydrates raw JSON into structured, typed PHP objects, including nested objects, arrays of objects, and custom value types. It is designed for the inbound transport boundary of an application, such as third-party API responses, webhook payloads, queue message envelopes, and event bus data. In Laravel it complements Eloquent casts, API Resources, and Form Requests rather than replacing them. Version 2.x can also serialize objects back to JSON.
- How do I install json-mapper/json-mapper in a Laravel project?
- Install it with composer require json-mapper/json-mapper. The library requires PHP 8.1 or newer because it relies on PHP attributes for mapping configuration. There is no Laravel service provider or facade shipped with the package, so you bind a configured mapper instance yourself in a service provider if you want container injection. The integration wrapper is small, typically around 150 to 250 lines including config and exception handling.
- Does json-mapper/json-mapper support Laravel, and is there a service provider?
- The package is framework-agnostic and has no Laravel coupling, service provider, or facade. Because it has no dependency on a specific Laravel version, it works alongside Laravel 9, 10, 11, and 12 as long as the PHP requirement of 8.1 or newer is met. In practice you add a thin service provider that binds a configured singleton, plus an optional config file. Treat that wrapper as disposable so you can swap mapping libraries later without touching your domain code.
- How do I map nested JSON objects and arrays to PHP classes?
- You define DTO classes and annotate properties with the package's attributes so the mapper knows which class to instantiate for each nested structure. Arrays of objects are mapped to typed collections rather than remaining untyped arrays, which removes hand-rolled fromArray loops. Custom handlers or middleware let you control key case conversion and other cross-cutting concerns through the AbstractMiddleware pipeline. Keeping strict mode on by default makes schema drift surface as a clear mapping exception instead of a silent null.
- How do I map JSON values to custom types like Carbon, Money, or UUID?
- Register custom handlers so the mapper knows how to convert a scalar or array value into your value object. This keeps DTOs free of conversion logic and avoids polluting them with library-specific semantics. You can also use the middleware pipeline for cross-cutting transformations such as key case conversion, logging via a PSR-3 logger, or caching. Map to DateTimeImmutable where possible so your DTOs stay framework-independent.
- What is the difference between json-mapper 1.x and 2.x?
- The major break in 2.x is the move from annotations to PHP attributes, which means most older tutorials and Stack Overflow answers describe the wrong API. Version 2.x also adds the ability to serialize objects back to JSON, though you should confirm unmap maturity in the exact version you pin. Always pin the major version explicitly in your team documentation and composer constraints. If you find examples online, check whether they use attributes or docblock annotations before copying them.
- How do I handle json-mapper exceptions in Laravel so invalid payloads return 422 instead of 500?
- Mapping failures are thrown as exceptions rather than Laravel ValidationExceptions, so without a translation layer a malformed inbound payload becomes a 500 and pollutes your error budget and alerting. Add a small exception-to-HTTP translation layer that catches mapping exceptions and rethrows them as a 422 JSON response, ideally with the failing field path. Register this in your exception handler so it applies consistently across webhook and API client boundaries. This also makes contract tests easier to assert against.
- Is json-mapper/json-mapper fast enough for high-volume queue and webhook processing?
- Mapping is reflection-driven and happens per payload, so there is a measurable CPU cost at high queue throughput. Check whether metadata or PSR-16 caching is available in the version you pin, and enable it if so. Benchmark against a hand-written hydrator on your actual payload shapes before putting it on a hot path. For most applications the cost is negligible compared to I/O, but it is worth measuring rather than assuming.
- Can json-mapper/json-mapper convert PHP objects back to JSON?
- Version 2.x adds object-to-JSON serialization, but the feature is less mature than inbound hydration, so verify it meets your needs in the specific version you pin. If you only need inbound DTO hydration, the outbound story in Laravel is already well served by API Resources and Eloquent casts. Avoid running two competing serialization stacks in one codebase, since that creates confusion about which layer owns the output shape. Decide early whether your need is inbound-only or truly bidirectional.
- How does json-mapper/json-mapper compare to spatie/laravel-data or Symfony Serializer?
- spatie/laravel-data is Laravel-native, integrates with validation, and is more opinionated, while Symfony Serializer is a mature general-purpose option already present transitively in some stacks. json-mapper is a smaller, single-purpose library focused on turning JSON into typed PHP objects, with no persistence or validation opinions. The trade-off is that you write the Laravel wrapper yourself, but the result is a thin, swappable edge layer. Evaluate all three against your actual payload complexity before committing to a hot path.