Self Aware Normalizers Laravel Package

Product Decisions This Supports

• Domain-Driven Design (DDD) Alignment: Enables self-contained value objects and DTOs to manage their own serialization/deserialization, reinforcing DDD principles by keeping normalization logic co-located with domain logic.
• API/Integration Layer Decoupling: Reduces coupling between domain models and API layers by allowing value objects to handle their own conversion to/from scalar data (e.g., JSON, form inputs). This simplifies API contracts and reduces boilerplate in controllers/serializers.
• Roadmap for Self-Describing Data: Supports future-proofing for systems where data structures evolve frequently (e.g., microservices, event-driven architectures). Normalization logic lives with the data, reducing migration pain.
• Build vs. Buy: Avoids reinventing normalization logic (e.g., custom serializers, manual mapping) while maintaining control over the process. Ideal for teams already using Symfony or Laravel with a DDD focus.
• Use Cases:
  • Complex DTOs: When DTOs require non-trivial validation/transformation during serialization (e.g., masking PII, formatting dates).
  • Event Sourcing: Ensuring events are normalized consistently before storage/deserialization.
  • GraphQL Resolvers: Reducing resolver complexity by offloading normalization to value objects.
  • Legacy System Integration: Bridging gaps between old systems (with rigid schemas) and modern APIs.

When to Consider This Package

• Adopt When:

  • Your team prioritizes DDD or clean architecture and wants to enforce self-contained domain logic.
  • You’re building or maintaining APIs with evolving schemas (e.g., microservices, headless CMS).
  • Normalization logic is complex or tightly coupled to domain models (e.g., nested objects, conditional fields).
  • You’re using Symfony Serializer or Laravel’s built-in serialization and want to delegate normalization to value objects.
  • Your project has high test coverage needs for serialization/deserialization paths (package includes mutation testing).

• Look Elsewhere If:

  • Your team prefers anemic models or passive data objects (normalization logic belongs in separate serializers).
  • You’re using simple, flat data structures (e.g., CRUD apps with basic JSON APIs).
  • Your stack is non-PHP/Symfony/Laravel (package is PHP-centric).
  • You need performance-critical serialization (this adds minor overhead for interface checks).
  • Your project lacks domain ownership (e.g., shared kernels where teams control serialization centrally).

How to Pitch It (Stakeholders)

For Executives:

"This package lets our domain models ‘speak for themselves’ when converting to/from APIs or databases. Instead of writing separate serializers or mappers—which can drift from the domain—our value objects handle their own normalization. This reduces technical debt, speeds up API evolution, and aligns with our DDD strategy. For example, if our Order object needs to mask customer emails in APIs but not in internal storage, the logic stays with the object, not scattered across controllers or serializers. It’s a small investment now that pays off in maintainability as we scale."

Key Outcomes:

• Faster API iterations (no serializer bottlenecks).
• Reduced bugs from schema drift.
• Cleaner codebase (logic co-located with data).

For Engineering:

*"This is a Symfony bundle (works in Laravel via Symfony components) that adds two interfaces to value objects/DTOs:

1. SelfNormalizable – Converts the object to scalar data (e.g., ['id': 123, 'name': 'Foo']).
2. SelfDenormalizable – Rebuilds the object from scalar data.

Why use it?

• No more manual mapping: Replace Serializer::normalize($order) with $order->normalize().
• Testable by design: Normalization logic is unit-testable alongside domain logic.
• Works with Symfony Serializer/Laravel: Plugs into existing stacks without rewrites.
• Future-proof: If your User DTO’s structure changes, the normalization updates automatically.

Trade-offs:

• Minor runtime overhead (interface checks).
• Requires discipline to keep normalization logic in value objects (not in controllers).

Proposal: Pilot this in our Orders module for API responses. If it reduces serializer bugs by 30% (as seen in similar projects), we’ll roll it out to other DTOs."*

Demo: Show a before/after of a UserDTO with/without self-normalization. Highlight how the object’s normalize() method replaces a 20-line serializer class.