- Does gbprod/uuid-normalizer work with Laravel?
- Yes, but only indirectly: the package ships just two plain classes, UuidNormalizer and UuidDenormalizer, implementing Symfony Serializer interfaces, with no service provider, config file or package auto-discovery. In a stock Laravel app that serializes Eloquent models through toArray, JsonResource, casts or FormRequests, it does nothing useful because symfony/serializer is not in the request path. It pays off only when you already build DTOs with symfony/serializer, such as an API Platform endpoint or a hexagonal boundary layer.
- How do I install gbprod/uuid-normalizer?
- Run composer require gbprod/uuid-normalizer; the package expects symfony/serializer and ramsey/uuid to be present in your dependency tree. Installation is not finished at that point, because there is no auto-registration step and you must wire both classes into a serializer instance yourself. The README lists PHP 7.4+ as the requirement.
- Why does Symfony Serializer throw "Not a time-based UUID" for Ramsey UUIDs?
- The default ObjectNormalizer treats a Ramsey\Uuid\UuidInterface as a regular object and walks its getters, and Uuid's timestamp accessor throws UnsupportedOperationException ("Not a time-based UUID") for anything that is not a v1 UUID. Registering UuidNormalizer ahead of ObjectNormalizer makes UUIDs serialize to their canonical string form instead. Normalizer ordering is the whole integration: if UuidNormalizer is not first in the list, the original exception returns intermittently.
- How do I register UuidNormalizer and UuidDenormalizer in a Laravel app?
- Compose the chain explicitly with a dedicated SerializerServiceProvider or an App\Support\SerializerFactory that builds new Serializer([new UuidNormalizer(), new DateTimeNormalizer(), new ObjectNormalizer(...)]) and binds it as a singleton. Laravel's container has no serializer.normalizer tag, so the YAML and XML service tags shown in the README only apply inside a Symfony application. Place UuidNormalizer before ObjectNormalizer and UuidDenormalizer before any object denormalizer.
- Which PHP, Laravel and Symfony versions does gbprod/uuid-normalizer support?
- The README states PHP 7.4+, and in practice you should target PHP 8.1+ with Laravel 10 to 12 plus symfony/serializer ^6 or ^7 and ramsey/uuid ^4. Compatibility with ramsey/uuid v5 and symfony/serializer v8 is unproven, so pin versions and cover the round trip with your own test. Nothing in the package is tied to a specific Laravel release.
- Does UuidDenormalizer handle malformed UUID strings?
- Exception mapping for invalid input is not documented in the README, so do not assume you get a clean 422 for free. UuidDenormalizer will let whatever Ramsey throws, typically InvalidUuidStringException, bubble up to your exception handler. Add a test that posts a malformed UUID and asserts the HTTP status before relying on default behaviour.
- Does gbprod/uuid-normalizer support nullable or optional UUID properties?
- Null values and missing keys are not addressed by the README, so both cases need to be proven by your own tests. Run a null UUID and an absent property through your real ObjectNormalizer chain before shipping. Many teams wrap the denormalizer or add a small custom normalizer to cover the nullable case explicitly.
- Should I use gbprod/uuid-normalizer together with laravel-data?
- No: if laravel-data is your DTO layer, skip this package entirely. laravel-data has its own transformer and cast system, and a custom DataTransformer or cast for Ramsey UUIDs is the idiomatic fix that avoids running two serialization stacks in the same request. Reach for this normalizer only when symfony/serializer already defines your serialization boundary.
- Does it conflict with Symfony's built-in UidNormalizer?
- Symfony 6.2+ ships UidNormalizer, but that class targets symfony/uid rather than ramsey/uuid, so the two do not collide. They only coexist awkwardly when a codebase carries both UUID libraries, which is worth resolving before adding anything else. This package is relevant specifically when Ramsey is the UUID of record, which is the Laravel case since Str::uuid() returns a Ramsey UUID.
- Is gbprod/uuid-normalizer safe to depend on in production?
- Treat it as adopt-with-vendored-fallback: the entire surface is roughly 100 lines across two classes, with a single maintainer, modest download counts and little evidence of large-scale production use. The license is WTFPL, which is permissive in practice but not OSI-approved and reliably flags in enterprise OSS scans. Because the code is small and reproducible in under a day, vendoring the two classes into App\Support is often cheaper than a procurement fight.