Marshaller Laravel Package

Technical Evaluation

Architecture Fit The spiral/marshaller package is a lightweight, attribute-driven object-to-array/array-to-object marshaling tool that excels in Laravel ecosystems requiring structured data transformation without heavy dependencies. It aligns with Laravel’s dependency injection, Eloquent, and API resource patterns, offering a declarative alternative to manual serialization (e.g., toArray() methods or Fractal). Key strengths:

• Attribute-based configuration: Uses PHP 8.1+ attributes (#[Marshal]) for zero-boilerplate mapping of public/private properties, enums, and nested objects.
• Type safety: Supports complex types (UUIDs, DateTimeImmutable, enums) via custom type handlers (e.g., EnumType).
• Nested structure handling: Recursively processes arrays of objects (e.g., delivery_addresses), reducing manual recursion logic.
• Extensibility: Pluggable mapper factories and decorators allow customization for edge cases (e.g., ignoring properties, renaming fields).

Integration Feasibility

• Laravel compatibility: Works seamlessly with:
  • Eloquent models: Replace toArray() with Marshaller::marshal($model) for consistent serialization.
  • API resources: Use as a drop-in for Illuminate\Http\Resources\Json\Resource or alongside Spatie’s Fractal.
  • Request validation: Unmarshal arrays into DTOs for type-safe input handling (e.g., unmarshal($request->all(), new UserDto())).
• Stack synergy: Integrates with Spiral’s ecosystem (e.g., spiral/attributes, spiral/core) and Laravel’s service container via bindings.
• Minimal overhead: Adds ~100KB to vendor dependencies (vs. ~500KB for Fractal).

Technical Risk

• Limited adoption: Low GitHub stars (1) and dependents (0) signal early-stage maturity; validate use cases with Spiral’s core team or community.
• Missing features:
  • No built-in circular reference handling (risk of infinite recursion with nested objects).
  • No JSON/XML/CSV output (focused on PHP arrays; requires manual conversion).
  • No Laravel-specific integrations (e.g., Illuminate\Validation rules, Illuminate\Http\Request decorators).
• Performance unknown: No benchmarks vs. alternatives (e.g., jms/serializer, manual mapping). Test with production-scale payloads.
• Attribute dependency: Requires PHP 8.1+ attributes; may conflict with existing annotation libraries (e.g., Doctrine).

Key Questions

1. Use case alignment:
   • Will this replace all serialization logic (e.g., Eloquent, API resources) or supplement it?
   • Are there circular references in your data models (e.g., User->orders->user)?
2. Team familiarity:
   • Is the team comfortable with attribute-based configuration vs. traditional methods (e.g., Arrayable)?
   • Are there existing serialization libraries (e.g., Fractal, jms/serializer) to compare?
3. Long-term viability:
   • Is Spiral’s maintenance commitment reliable (check Spiral’s roadmap)?
   • Are there plans to add Laravel-specific integrations (e.g., validation, request binding)?
4. Testing requirements:
   • How will you test edge cases (e.g., invalid input arrays, unsupported types)?
   • Will you need to mock the Marshaller in unit tests?

Integration Approach

Stack Fit

• Laravel core: Replace or extend:
  • Eloquent toArray(): Use Marshaller::marshal($model) in AppServiceProvider or model traits.
  • API resources: Override toArray() to delegate to Marshaller for nested objects.
  • Request handling: Unmarshal Request input into DTOs (e.g., unmarshal($request->all(), new CreateUserDto())).
• Validation: Pair with Laravel’s Illuminate\Validation by unmarshaling validated data into objects.
• Microservices: Standardize payload formats across services using shared DTOs.

Migration Path

1. Pilot phase:
   • Start with one API endpoint or Eloquent model to test Marshaller::marshal().
   • Compare output with existing toArray() implementations for consistency.
2. Incremental adoption:
   • Replace manual toArray() methods in critical models/resources (e.g., User, Order).
   • Use decorators (e.g., MarshallerDecorator) to customize behavior without modifying core logic.
3. Full integration:
   • Bind Marshaller to Laravel’s container in AppServiceProvider:

     $this->app->singleton(Marshaller::class, fn() => new Marshaller(
         new AttributeMapperFactory(new AttributeReader())
     ));
     

   • Create a base trait for models/resources:

     trait MarshallsAttributes
     {
         public function toArray(): array
         {
             return app(Marshaller::class)->marshal($this);
         }
     }
     

Compatibility

• PHP 8.1+ required: Ensure all team environments support attributes and typed properties.
• Attribute conflicts: Avoid mixing with other annotation libraries (e.g., Doctrine ORM). Use namespaces or disable conflicting readers.
• Type support: Ensure all serialized types (e.g., UUIDs, enums) have custom type handlers registered.

Sequencing

1. Phase 1 (Week 1):
   • Install package and test basic marshaling (Marshaller::marshal($object)).
   • Validate output against existing toArray() methods.
2. Phase 2 (Week 2):
   • Integrate with Eloquent models (replace toArray()).
   • Test nested objects (e.g., User->addresses).
3. Phase 3 (Week 3):
   • Add unmarshaling for request DTOs.
   • Implement custom type handlers (e.g., for Carbon instances).
4. Phase 4 (Ongoing):
   • Extend to API resources and validation layers.
   • Monitor performance and edge cases.

Operational Impact

Maintenance

• Pros:
  • Reduced boilerplate: Centralized serialization logic cuts maintenance overhead for toArray() methods.
  • Consistent behavior: Attributes enforce uniform mapping rules across the codebase.
• Cons:
  • Dependency risk: Vendor lock-in to Spiral’s ecosystem (though MIT-licensed).
  • Debugging complexity: Attribute-based mapping may obscure serialization logic in stack traces.

Support

• Learning curve: Team will need to:
  • Understand attribute syntax (#[Marshal], #[MarshalArray]).
  • Learn custom type handling for unsupported types (e.g., Carbon).
• Documentation gaps: Lack of Laravel-specific guides; may require internal docs for:
  • Integration with Illuminate\Http\Request.
  • Handling validation errors during unmarshaling.

Scaling

• Performance:
  • No known bottlenecks for typical Laravel use cases (e.g., API responses).
  • Caching: Consider caching marshaled results for frequently accessed objects (e.g., User profiles).
  • Benchmark: Compare with alternatives (e.g., Fractal) for high-throughput APIs.
• Horizontal scaling: Stateless marshaling works well in queued jobs or microservices.

Failure Modes

Ramp-Up

• Onboarding:
  • Workshop: 1-hour session on attributes, basic marshaling, and custom types.
  • Cheat sheet: Document common use cases (e.g., "How to marshal an Eloquent model").
• Training materials:
  • Example repo: Seed with a Marshaller-integrated Laravel app.
  • Comparison guide: Highlight differences vs. Fractal/manual mapping.
• Adoption metrics:
  • Track reduction in toArray() boilerplate.
  • Measure developer satisfaction via surveys or PR review times.

Monitoring

• Logs: Monitor for:
  • MarshallerException (e.g., unsupported types).
  • Performance degradation (e.g., slow marshaling of large