Fractal Bundle Laravel Package

Product Decisions This Supports

• API response layer architecture (build vs. buy): Fractal is a transformation/presentation layer between your domain models and API payloads. Adopting it is a decision to standardize how every endpoint shapes JSON — includes, embedded relationships, sparse fieldsets, and serializer formats (array, JSON-API, HAL) — rather than hand-rolling toArray() methods per controller.
• API contract stability and versioning: If your roadmap includes public/partner APIs, external consumers, or a v1 → v2 migration, Fractal's transformer abstraction lets you version output without touching domain code. That is a product-risk reduction argument, not just a code-style argument.
• Symfony modernization / upgrade unblocking: This package is a port of the abandoned samj/fractal-bundle. Its clearest product value is as a migration path: if you already depend on Fractal via the original bundle, this is the drop-in that lets you move to current Symfony/PHP versions instead of rewriting your entire serialization layer under deadline.
• Build vs. buy scope: The bundle is thin glue (DI registration, config, transformer resolution). The real dependency is league/fractal. The decision this informs is "do we take a dependency on a near-zero-adoption wrapper, or wire Fractal ourselves in ~100 lines of service configuration?" — a maintenance-burden tradeoff, not a feature tradeoff.
• Framework strategy: This is Symfony, not Laravel. If the roadmap involves Laravel, this package is out of scope entirely; the equivalents there are Laravel API Resources (first-party) or spatie/laravel-fractal. Surfacing that mismatch early prevents wasted evaluation cycles and a wrong item on the tech-radar.
• Use cases it fits: Internal/back-office APIs, small-to-mid services with a handful of resource types, teams already fluent in Fractal's transformer/include syntax, and legacy Symfony apps with an existing Fractal investment.
• Use cases it does not fit: Anything needing generated OpenAPI docs, first-class hypermedia, or schema validation as a product requirement — that is API Platform territory on Symfony, and choosing this bundle would leave that gap to be filled later at higher cost.

When to Consider This Package

Adopt (or at least pilot) when:

• You are on Symfony and already use, or are explicitly committed to, league/fractal as the presentation layer.
• You are migrating off samj/fractal-bundle and want the smallest possible diff — the port exists specifically to keep existing transformer registrations working.
• Your API surface is small and stable: a modest number of resources, no requirement for auto-generated API documentation.
• Your team accepts vendor risk: 3 stars, 0 dependents, and a composite score of 0.045 mean effectively no community, no upstream support contract, and no signal that security or Symfony-version compatibility will be maintained. Budget for forking or vendoring it, and confirm the license (MIT — permissive, so forking is legally clean).
• You have verified PHP and Symfony version constraints yourself; with zero dependents there is no crowd-sourced compatibility evidence.

Look elsewhere when:

• You are on Laravel — use first-party API Resources, or spatie/laravel-fractal if you specifically want Fractal semantics. This package does not apply.
• You want a supported, feature-rich API layer on Symfony — API Platform covers serialization, OpenAPI/JSON Schema generation, hypermedia, pagination, and validation in one maintained package. That is a bigger commitment but a far smaller support risk.
• Your needs are simple enough for Symfony Serializer with serialization groups — no extra dependency, no abandonment risk.
• You require vendor SLAs, security patching guarantees, or a package with meaningful downstream usage. Three stars and zero dependents is a hard stop for regulated or long-lived products.
• Your team has no Fractal familiarity — the learning cost lands on you, and the bundle adds no ergonomics beyond wiring.

Diligence before committing: check last commit date and open-issue count on the repo, run the test suite against your target Symfony/PHP versions, and decide in advance who owns the fork if upstream goes quiet.

How to Pitch It (Stakeholders)

For executives: This is a small, permissively licensed (MIT) integration package that standardizes how our Symfony APIs shape their JSON output, and — more importantly — it gives us a low-risk exit from an abandoned dependency we'd otherwise be stuck on. It is not a strategic platform bet: it has negligible community adoption and no vendor support, so we should treat it as glue we may need to own. Recommendation: adopt only where it unblocks an upgrade or preserves an existing Fractal investment; for any new API build, evaluate API Platform instead, since it delivers documentation and schema generation we'd otherwise build ourselves.

For engineering: The bundle is thin — DI configuration plus transformer resolution around league/fractal. Two consequences: the real dependency is Fractal itself, and if the wrapper goes stale we can inline it in roughly a day. Fractal gives us a clean presentation layer with includes, sparse fieldsets, and pluggable serializers (array, JSON-API, HAL), which decouples API contracts from domain models and makes versioning tractable. Caveats to accept explicitly: near-zero downstream usage, no maintainer guarantees, and no OpenAPI generation — verify Symfony/PHP compatibility in CI rather than trusting the metadata. And confirm scope: this is a Symfony bundle; if the service in question is Laravel, this is the wrong tool and we should stop the evaluation here.