Uuid Normalizer Laravel Package

Product Decisions This Supports

• API contract consistency: Forces Ramsey UUID value objects to serialize as canonical strings and denormalize back into typed objects, so we can standardize on "UUIDs are always strings on the wire" without ad-hoc (string) casting scattered through controllers and resources.
• Build vs. buy (buy, trivially): This replaces ~20 lines of custom Normalizer/Denormalizer code plus the tests and edge cases (invalid UUID input, variant/version handling) that come with it. At this scope the decision is not strategic — it is a maintenance-cost decision, and the answer is to take the dependency if we already run Symfony Serializer.
• Feature scope for typed-domain work: Supports features where identifiers are modeled as UuidInterface in the domain layer rather than raw strings — e.g., typed DTOs for request/response payloads, event payloads, or message-queue envelopes. This is the package's real enabling value: it removes the serializer friction that otherwise pushes teams back to string-typed IDs.
• Error-handling roadmap input: The README's cited failure mode (UnsupportedOperationException: Not a time-based UUID) is a 500-level symptom of a missing normalizer. Adopting the package lets us define a deliberate 400/422 contract for malformed UUIDs instead of leaking 500s.
• Use cases where it fits: Symfony applications; Laravel applications that have deliberately adopted symfony/serializer (common in DDD/hexagonal codebases, or where serialization is used for API versioning or message payloads); any PHP service where Ramsey UUIDs and Symfony Serializer coexist.
• Use cases where it does not change our roadmap: Standard Laravel API work. Eloquent casts (HasUuids, uuid cast) and API Resources already handle UUID-to-string and string-to-UUID; this package adds nothing there and should not be presented as a Laravel serialization solution.

When to Consider This Package

Adopt when all of these hold:

• We use ramsey/uuid for domain identifiers and symfony/serializer for request/response or message serialization in the same service.
• We are currently casting UUIDs to strings manually in normalizers, transformers, or DTOs, or we are hitting the "Not a time-based UUID" / UnsupportedOperationException class of bug.
• We want typed UUIDs in DTOs and message contracts rather than strings, and we want that to work without custom serializer plumbing.
• We are comfortable with a small, single-purpose, single-maintainer dependency.

Look elsewhere or skip when:

• It is a plain Laravel app. Use Eloquent casts and API Resources; symfony/serializer is not the default serialization path, so the package solves a problem we do not have.
• We use JMS Serializer or Laravel's own JSON responses. The package is explicitly Symfony Serializer-only.
• We only need UUIDs as strings. ramsey/uuid's __toString and a route/attribute cast is sufficient; no normalizer required.
• Governance is strict. WTFPL is a permissive but unusual license that will trip some legal/procurement reviews; 0 dependents and a single maintainer mean no ecosystem backstop. Budget for the (small) possibility of vendoring the two classes.
• We need more than UUIDs. If we are assembling a broader normalizer set (money, enums, date-time value objects), look at a maintained collection or write a thin internal bundle rather than accumulating micro-dependencies.

Adoption checklist before merging: confirm the version is compatible with our symfony/serializer major, confirm the normalizer is registered with correct priority relative to other normalizers (ordering matters for how UuidInterface is matched), and add one contract test that asserts a malformed UUID produces our intended 4xx rather than a 500.

How to Pitch It (Stakeholders)

For executives: This is a small, low-risk open-source utility that removes a class of 500 errors and eliminates roughly a day of custom plumbing plus ongoing upkeep per service that models identifiers as UUID objects. It is not a platform decision or a strategic bet — it is a maintenance-cost reduction with a clear, narrow blast radius. Cost is a single Composer dependency; risk is limited to a permissively licensed, single-maintainer package that we could vendor in an afternoon if it were ever abandoned. Recommendation: approve for Symfony-serialized services; do not include in standard Laravel service templates.

For engineering: gbprod/uuid-normalizer supplies the UuidNormalizer/UuidDenormalizer pair that Symfony Serializer is missing, so UuidInterface properties on DTOs round-trip as canonical strings without hand-written normalizers. Register both under the serializer.normalizer tag, mind normalizer priority, and cover malformed input with an explicit 4xx assertion. Caveats: Symfony Serializer only — Laravel's cast/Resource path makes this redundant; the project is small (30 stars, 0 dependents, single maintainer) and WTFPL-licensed, so treat it as a vendorable two-class dependency rather than infrastructure. Pin the version and keep a contract test around UUID serialization so a future swap is a non-event.