Marshaller Laravel Package

Product Decisions This Supports

• Standardized Data Transformation: Eliminates inconsistencies in manual JSON/API payload serialization across teams, ensuring uniform data contracts for APIs, databases, and microservices.
• API Development Roadmap: Enables faster iteration on API endpoints by reducing boilerplate for request/response mapping, aligning with Laravel’s ecosystem (e.g., pairing with Laravel Sanctum, API Resources, or GraphQL).
• Build vs. Buy Decision: Justifies avoiding custom serialization libraries or reinventing wheel for object-to-array conversions, lowering long-term maintenance costs.
• Use Cases:
  • Complex Data Structures: Handles nested objects, collections, and custom types (e.g., UUIDs, enums) without manual mapping logic.
  • Legacy System Integration: Bridges gaps between modern PHP objects and legacy systems expecting flat arrays or JSON.
  • Event-Driven Architectures: Standardizes event payloads (e.g., Laravel Horizon jobs or message queues) for consistency across services.
  • Testing & Mocking: Simplifies creation of test data by automating object hydration from arrays (e.g., unmarshal for factory patterns).

When to Consider This Package

• Adopt if:

  • Your Laravel application deals with frequent object-to-array/JSON conversions (e.g., Eloquent models, DTOs, or complex API payloads).
  • You need type safety and consistent serialization for nested structures (e.g., relationships, collections, or custom types like UUIDs/enums).
  • Your team prioritizes developer productivity over minimalistic solutions (e.g., replacing manual toArray() methods or json_encode() hacks).
  • You’re open to Spiral’s ecosystem (e.g., potential future integrations with Spiral Framework or other Spiral packages).
  • Your use case involves minimal configuration for basic scenarios (e.g., auto-mapping public properties).

• Look elsewhere if:

  • Your stack is non-PHP/Laravel (e.g., Node.js, Python, or Go).
  • You require high-performance serialization (e.g., for real-time systems or game engines)—this is not optimized for binary formats like MessagePack or Protocol Buffers.
  • Your project is simple CRUD APIs with trivial JSON handling (e.g., basic REST endpoints without nested data).
  • You need circular reference handling out of the box (v1.0.0 lacks explicit support; evaluate alternatives like jms/serializer or symfony/serializer if critical).
  • Your team prefers declarative XML/JSON schemas (e.g., OpenAPI/Swagger) over attribute-based configuration.

How to Pitch It (Stakeholders)

For Executives: "Marshaller standardizes how our Laravel APIs handle data serialization, cutting development time on repetitive JSON mapping tasks by 30–50% while reducing bugs. It’s a lightweight, MIT-licensed solution from Spiral Labs—used in production by their framework—that aligns with our tech stack. Initial adoption is low-risk (v1.0.0 is stable for basic use cases), with scalability for complex scenarios like microservices or legacy integrations. This reduces technical debt and accelerates API development without vendor lock-in."

For Engineers: *"Marshaller replaces manual array_merge/json_encode hacks with a declarative, type-safe approach. Key wins:

• Auto-mapping: Public properties of objects/collections serialize to arrays/JSON with zero config.
• Laravel-friendly: Works seamlessly with Eloquent, API Resources, and request validation (e.g., unmarshal for input binding).
• Extensible: Customize rules via attributes (e.g., ignore properties, rename fields, or handle enums/UUIDs). Start with Marshaller::toArray($object) for quick wins. For advanced use cases (e.g., circular references), pair with PHPUnit or evaluate jms/serializer as a backup. The learning curve is minimal if you’re familiar with Spiral’s annotations or Laravel’s attributes."

For Architects/Tech Leads: *"This package addresses data transformation consistency across our Laravel monolith/microservices. Benefits:

• Reduces cognitive load: No more ad-hoc serialization logic per endpoint.
• Future-proof: Supports Spiral’s ecosystem (e.g., potential GraphQL or event-driven integrations).
• Testability: Simplifies mocking/hydration for unit/integration tests. Recommend piloting in a high-impact API (e.g., user profiles or orders) to validate ROI. Monitor performance against alternatives like Fractal or manual mapping for edge cases."