Fractal Bundle Laravel Package

Product Decisions This Supports

• Presentation-layer architecture: serialize vs. transform. This package supports the decision to introduce an explicit transformation layer between domain models and API responses, rather than leaking entities/ORM objects into JSON. That is a contract-stability decision with real cost-of-change implications for public APIs, mobile clients, and partner integrations.
• Dependency injection strategy for presentation code. The bundle's single meaningful idea is container-managed transformers — a transformer can receive repositories, URL generators, locale/tenant context, feature-flag services, or authorization checks via constructor injection. That supports the decision "transformers are first-class services, not static helpers," which in turn makes them testable and mockable in isolation.
• Build vs. buy for glue code. Assessed honestly, this is ~200 lines of compiler pass plus a service definition. The build-vs-buy answer is heavily weighted toward "build" — the pattern is the asset, not the artifact. Use this package as a reference implementation when scoping an internal transformation layer.
• Legacy maintenance vs. rewrite triage. For a team owning a Symfony 2.x/3.x application, this informs whether to keep patching the existing response layer or schedule a migration to Symfony Serializer / API Platform. The dependency itself is archived with no dependents, which makes it a candidate for "freeze and plan exit" rather than "extend."
• Roadmap inputs for API surface work. Relevant to features that change response shape: sparse fieldsets, embedded/nested includes, pagination metadata envelopes, API versioning, and per-client response variants. Fractal's include/serializer model is a good conceptual frame for those roadmap items even if the package is not adopted.
• Ecosystem-fit correction. Scored as a "Laravel/PHP package," it is in fact a Symfony2 bundle. Any product decision must account for that: it is not a candidate for a Laravel codebase, where Spatie's laravel-fractal, API Resources, or plain league/fractal are the realistic options.

When to Consider This Package

Consider it when all of the following hold:

• You are maintaining a Symfony 2.x or 3.x application on the older service-container conventions where bundle-provided compiler passes and services.yml loading are the norm.
• You are already using league/fractal and have hit the friction point where transformers need collaborators (repositories, tenant context, URL signing) and are currently doing service-locator hacks or new-ing dependencies inside transform().
• Your transformers have genuine non-trivial dependencies — not just formatting — so container wiring buys you real testability rather than ceremony.
• You accept no upstream maintenance: archived repository, last release June 2020, zero dependents, ~27 stars. That is acceptable only if you are willing to fork or vendor the code and own it.

Look elsewhere when any of the following hold:

• New Symfony projects (4.x–7.x). Native autowiring, !tagged_iterator, and Autoconfigure attributes make the bundle's core value proposition redundant; you can register transformers as services and inject the Fractal Manager directly in an afternoon.
• Laravel applications. Wrong framework entirely. Use spatie/laravel-fractal, Eloquent API Resources, or hand-rolled transformers with container resolution.
• You want a maintained dependency. Archived + 2020 + zero dependents is a supply-chain and security-patch signal. Do not put it on a path that requires CVE response.
• You need schema-first or documentation-driven APIs. API Platform, symfony/serializer with serialization groups, or a DTO/hydration approach (e.g., cuyz/valinor) gives you OpenAPI generation, validation, and typed contracts that Fractal-plus-glue does not.
• Your transformation needs are simple. If responses are close to your entities, a serializer with groups is less machinery and fewer concepts for the team to learn.
• You need pagination, includes, and sparse fieldsets out of the box with modern framework support. Fractal's features are strong, but the bundle is not the reason to choose it.

Decision rule: treat the package as a pattern reference, not a dependency. The reusable insight — transformer-as-service with constructor injection — should be copied into your own thin integration, which you then own and can keep current.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, single-purpose glue library that connects a response-transformation library to Symfony's dependency injection container. It costs almost nothing to evaluate and nothing to replace — but it is archived, has had no release since 2020, and no known downstream users, so it is not something we should build a roadmap on. The strategic value is the pattern it demonstrates: keeping API response shaping in dedicated, injectable, unit-testable classes rather than scattering it through controllers. Recommendation: adopt the pattern internally, do not adopt the dependency for anything customer-facing.

To engineering leadership: The artifact is ~a compiler pass and a service definition. Its only durable contribution is normalizing "transformers are container services." We can reproduce that in our own codebase in roughly a day, retain full control, and stay compatible with current Symfony. Adopting the archived bundle instead buys us a fork obligation with no maintenance upside. Where we are on Symfony 2/3 and already standardized on league/fractal, a short-lived adoption (or vendoring) is defensible as a bridge; anywhere else, it is net-negative.

To the engineering team: Use this repository as a worked example of wiring third-party managers into a container and injecting collaborators into transformers — read it, then write our own integration with tagged services and constructor injection. Standardize on one transformation approach per API surface, keep transformers dependency-injected and independently testable, and make the response envelope (pagination, includes, errors) an explicit, versioned contract rather than an accident of ORM serialization.