Output Normalizer Bundle Laravel Package

Product Decisions This Supports

• API/Response Standardization: Enables consistent, declarative API response formatting across microservices or monolithic applications, reducing boilerplate in controllers and serializers.
• Decoupled Data Contracts: Allows defining output schemas separately from business logic (e.g., DTOs), improving maintainability and enabling gradual API evolution.
• Custom Field Transformation: Supports complex transformations (e.g., masking PII, aggregating nested objects) without modifying core entities or controllers.
• Roadmap for API Versioning: Facilitates backward-compatible API changes by isolating output logic from business logic (e.g., adding [EntityToId] to new versions without breaking existing clients).
• Build vs. Buy: Justifies not building a custom serializer when the package offers:
  • Flexibility: Fine-grained control over field inclusion/exclusion, naming conventions (snake_case), and transformations.
  • Performance: Leverages Symfony’s Normalizer under the hood for nested object handling.
  • Extensibility: Supports custom modifiers for domain-specific logic (e.g., role filtering, sensitive data redaction).
• Use Cases:
  • Legacy System Modernization: Gradually standardize inconsistent API responses in Doctrine-based apps.
  • Multi-Tenant APIs: Dynamically adjust output fields per tenant (e.g., hide deleted_at for public-facing APIs).
  • GraphQL-like Projections: Define ad-hoc output shapes for specific client needs without GraphQL overhead.

When to Consider This Package

• Adopt if:
  • Your app uses Doctrine ORM and needs consistent API responses without manual serialization in controllers.
  • You require fine-grained control over field naming (e.g., snake_case), inclusion/exclusion, or transformations (e.g., EntityToId for relationships).
  • Your team prefers declarative DTOs over annotations (e.g., Symfony’s #[Groups]) or JSON:API metadata.
  • You need custom output logic (e.g., modifying arrays, concatenating fields) without bloating entities or controllers.
• Look elsewhere if:
  • You’re using non-Doctrine entities (package assumes ORM relationships).
  • Your API is simple (e.g., 1:1 field mapping) and doesn’t need transformations.
  • You’re already using a mature serializer (e.g., Symfony Serializer, JMS Serializer) with sufficient extensibility.
  • Your team lacks PHP 8.1+ or Symfony 5.4+/6.0+ (dependency constraints).
  • You need performance-critical serialization (package adds minor overhead for flexibility).

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us standardize API responses without sacrificing flexibility. Instead of manually serializing data in every controller—wasting dev time and risking inconsistencies—we’ll define clean, reusable output rules (like DTOs) that automatically shape responses. For example:

• Reduce tech debt: Replace ad-hoc json_encode($entity) with declarative schemas.
• Future-proof APIs: Easily add/remove fields for new clients (e.g., mobile vs. admin dashboards) without breaking changes.
• Security: Centralize sensitive data redaction (e.g., PII masking) in one place. It’s a low-risk investment (MIT license, minimal dependencies) that pays off in maintainability and developer velocity."*

For Engineers:

*"This is a lightweight alternative to Symfony Serializer for Doctrine apps, with key advantages:

• No annotations: Define output shapes via plain PHP classes (e.g., UserOutput), making it explicit and IDE-friendly.
• Built-in transformations:
  • Auto-convert camelCase → snake_case (e.g., userName → user_name).
  • Extract only IDs for relationships (#[EntityToId]).
  • Modify data via custom modifiers (e.g., filter roles, format phone numbers).
• Symfony-native: Integrates with DI, Config, and HTTP Kernel—no framework lock-in.
• Extensible: Need to normalize a Phone object as +123456? Just implement ObjectNormalizerInterface.

Trade-offs:

• Slightly more verbose than annotations (but more maintainable long-term).
• Not a drop-in replacement for Symfony Serializer (e.g., no circular reference handling out of the box).

Proposal:

1. Pilot: Use it for 1–2 high-traffic endpoints to validate performance/usability.
2. Gradual adoption: Replace manual json_encode in controllers with OutputNormalizer.
3. Custom modifiers: Offload business logic (e.g., role filtering) from controllers to modifiers.

Example win:

// Before: Controller bloated with serialization logic
return json_encode([
    'id' => $user->getId(),
    'name' => $user->getFullName(), // Business logic in controller
    'city' => $user->getCity()->getId(), // Manual ID extraction
]);

// After: Declarative and DRY
return $this->outputNormalizer->normalize($user, UserOutput::class);

UserOutput.php:

class UserOutput implements OutputInterface {
    public int $id;
    public string $name;
    #[EntityToId] public City $city; // Auto-extracts city ID
}
```"*