Fractal Laravel Package

Product Decisions This Supports

• API Contract Stability: Adopt Fractal to enforce a strict separation between internal data models (e.g., Eloquent, Doctrine) and API responses. This ensures backward compatibility for clients (mobile apps, third-party services) when schema evolves, reducing churn and support costs.

  • Example: A SaaS platform with a public API can safely refactor database tables without breaking existing integrations.

• Roadmap Prioritization:

  • Phase 1 (MVP): Use Fractal for core API endpoints where data complexity is high (e.g., nested resources like users.posts.comments).
  • Phase 2 (Scale): Extend to internal microservices or headless CMS outputs to standardize payloads across teams.
  • Phase 3 (Standards): Align with JSON:API or HAL for interoperability if targeting enterprise clients or open-source ecosystems.

• Build vs. Buy:

  • Buy: Avoid reinventing a transformation layer for:
    • Relationship embedding (e.g., include=posts).
    • Pagination (Laravel, Doctrine, Pagerfanta adapters).
    • Schema validation and type casting (e.g., converting timestamps to ISO strings).
  • Custom Build Only If: Your API has unique serialization needs (e.g., binary data, WebSocket payloads) or you’re locked into a non-PHP stack.

• Key Use Cases:

  • Nested Data APIs: Replace manual foreach loops for relationships (e.g., UserTransformer with include=posts.comments).
  • Multi-Format Outputs: Generate JSON, XML, or custom formats from a single transformer layer.
  • Pagination: Integrate with Laravel’s paginator or third-party libraries (Phalcon, Doctrine) without duplicating logic.
  • Fieldsets/Sparse Data: Expose only requested fields (e.g., fields[user]=id,name) to optimize bandwidth for mobile clients.
  • Meta Data: Attach custom metadata (e.g., API version, caching headers) to responses globally or per-resource.

When to Consider This Package

Adopt Fractal if:

• Your API outputs complex, hierarchical data (e.g., users with posts, comments, and nested tags) and requires consistent, client-friendly payloads.
• You need to decouple API responses from database schema changes to avoid breaking existing clients (e.g., mobile apps, third-party services).
• Your team uses Laravel/PHP and wants a maintained fork of Fractal (the original thephpleague/fractal is stagnant).
• You require standard-compliant serialization (JSON:API, HAL) or custom formats without building pagination/embedding from scratch.
• You’re starting a new API or migrating an existing one to enforce consistency and reduce technical debt.
• Your API consumes large datasets and needs efficient pagination (supports Laravel, Doctrine, Pagerfanta, etc.).
• You want to reduce boilerplate in controllers by centralizing transformation logic in transformers.

Look Elsewhere if:

• Your API is simple (e.g., flat CRUD endpoints) and doesn’t need transformation layers.
• You’re using non-PHP backends (Node.js, Python, Ruby) or frameworks with built-in solutions (e.g., Django REST Framework, Rails ActiveModel Serializers).
• Your team lacks PHP/Laravel expertise or prefers GraphQL (which handles nesting natively via resolvers).
• You need real-time updates (WebSockets) or binary data (use raw json_encode or custom serializers).
• You’re constrained by PHP < 8.1 (Fractal requires PHP 8.1+).
• Your API is internal-only and doesn’t require schema stability for external clients.

How to Pitch It (Stakeholders)

For Executives (Business/Strategy)

"Fractal is a battle-tested tool to future-proof our API investments. By adopting this package, we can:

• Reduce API churn: Ensure backward compatibility for mobile apps and third-party integrations when we update database schemas.
• Accelerate development: Cut weeks of custom code for nested data, pagination, and serialization—letting engineers focus on core features.
• Standardize outputs: Deliver consistent, client-friendly payloads across all endpoints, improving reliability for partners.
• Support scalability: Easily extend to microservices or headless CMS outputs as we grow, without duplicating transformation logic. This is a low-risk, high-reward decision—like adding a seatbelt to our API’s growth trajectory."

For Engineering (Technical)

"Fractal solves three critical pain points in our API:

1. Schema Decoupling: Transformers act as a protective layer between Eloquent models and API responses. Change a database column? No breaking changes for clients.
2. Nested Data: Replace manual foreach loops for relationships (e.g., User->posts->comments) with declarative includes (e.g., ?include=posts.comments).
3. Standards Compliance: Built-in support for JSON:API and HAL, plus custom serializers. Pagination adapters for Laravel, Doctrine, Pagerfanta, etc. Migration is straightforward: swap thephpleague/fractal for this maintained fork, and reuse existing transformers with minimal changes. Let’s pilot it on our /users endpoint to validate ROI."

For Developers (Implementation)

"Here’s how we’ll roll this out:

• Phase 1: Replace json_encode($model) in controllers with Fractal’s Manager for 2–3 high-traffic endpoints (e.g., /users, /posts).
• Phase 2: Standardize transformers for all Eloquent models, using include params for nested data (e.g., GET /users?include=posts.comments).
• Phase 3: Extend to pagination (Laravel’s paginator) and fieldsets (e.g., fields[user]=id,name) for mobile optimization. Key benefits:
• No breaking changes: Transformers shield clients from schema updates.
• DRY code: Centralize serialization logic in transformers, not controllers.
• Future-proof: Supports JSON:API, HAL, or custom formats out of the box. Let’s start with a spike on /users to measure performance and developer productivity gains."