Weave Code
Laravel Fractal Laravel Package
gathercontent/laravel-fractal
A Laravel wrapper for the Fractal library that helps you transform Eloquent models, collections, and paginators into clean API responses with support for includes, serializers, and flexible resource transformations.
A Fractal Service Provider for Laravel
Frequently asked questions about Laravel Fractal
- How do I install gathercontent/laravel-fractal in a Laravel app?
- Install it with Composer using composer require gathercontent/laravel-fractal. Laravel package auto-discovery registers the service provider and facade, so no manual provider wiring is usually needed. If you need to change the default serializer, publish the package config and adjust it there.
- Which Laravel and PHP versions does gathercontent/laravel-fractal support?
- The package's composer.json is the source of truth for its declared Laravel and PHP constraints, so check those before committing. The technical assessment flags Composer constraint drift against newer Laravel and PHP releases as the most likely breakage. Validate the constraints against your current and next-upgrade targets and pin league/fractal to a tested minor.
- How do I configure the default Fractal serializer in Laravel?
- The package ships a publishable config file that controls the default Fractal serializer. Publish the config and choose Array or JSON-API early, because the serializer changes your public response contract. Keep that choice documented and covered by endpoint contract tests.
- Can I use gathercontent/laravel-fractal with Eloquent models and paginators?
- Yes. The wrapper is designed to transform Eloquent models, collections, and paginators into Fractal responses, with pagination adapters available through the underlying library. It binds league/fractal's Manager into Laravel's container and exposes it through a facade and helper functions. That makes it suitable for controllers that return model or paginator-backed API payloads.
- Does laravel-fractal support includes and sparse fieldsets?
- Yes, because it wraps league/fractal, so Fractal includes and serializer features such as sparse fieldsets and JSON-API or array output are available. The caveat is that include resolution can create hidden N+1 queries if relationships are not audited. Test query counts on include-heavy endpoints and establish include conventions.
- Is gathercontent/laravel-fractal still maintained and safe for production?
- Treat it as a small, low-footprint dependency rather than a heavily scrutinized framework component. The assessment notes roughly 50 stars, a low score, limited community support, and single-maintainer/backer risk, while league/fractal itself has a slower release cadence. It can be used in production if you pin versions, monitor abandonment and constraint drift, and keep a low-effort fork or vendor contingency.
- What are alternatives to laravel-fractal for Laravel API resources?
- The main alternative is Laravel's native Eloquent API Resources, including JsonResource classes, which cover much of the same model-to-response ground. You could also integrate league/fractal directly if you want Fractal's transformer and serializer model without this wrapper. Choose based on whether you need Fractal-specific features such as JSON-API serialization or cursor pagination adapters.
- How do I migrate from laravel-fractal to Laravel's native API Resources?
- Keep transformers in a dedicated namespace and treat them as a bounded presentation layer rather than core domain code. To migrate, port transformer logic into JsonResource classes endpoint by endpoint and keep contract tests to confirm payload parity. This incremental path avoids a project-wide rewrite and lowers exit cost if the package is abandoned.
- Can I use laravel-fractal for only some endpoints without refactoring the whole API?
- Yes. The assessment describes low integration cost and says one endpoint can adopt it without a project-wide refactor. Introduce the provider, then migrate endpoints one at a time behind transformers while leaving legacy responses untouched. This sequencing also lets you establish serializer and pagination conventions before broader rollout.
- How do I test endpoints that use gathercontent/laravel-fractal transformers?
- Cover transformers with focused unit tests and endpoints with HTTP contract tests that assert JSON structure and payload parity. Include query-count assertions on include-heavy responses to catch Fractal-induced N+1 patterns. Also test serializer and pagination behavior explicitly, since those settings define your public API contract.
Weaver
How can I help you explore Laravel packages today?