How to install spatie/laravel-fractal in Laravel?

Use Composer: run `composer require spatie/laravel-fractal`. The package auto-registers in Laravel 5.5 and up. For custom configurations like serializers, publish the config file with `php artisan vendor:publish`.

What's better: laravel fractal or Laravel API resources?

Laravel Fractal is more powerful for complex transformations and adheres to JSON:API standards with features like auto-includes, while Laravel's API resources are simpler, built-in, and better for basic JSON structuring. Choose based on transformation needs.

How to create a custom transformer with laravel fractal?

Run `php artisan make:transformer` to generate a dummy transformer stored in `app\Transformers`. Define transformation logic in the class, such as mapping fields, and use it with `transformWith()` in your code.

Can laravel fractal handle paginated API responses?

Yes, it supports pagination through Fractal's paginators. Configure the default paginator in the config file or use provided methods to integrate with Laravel's paginator for seamless paginated outputs.

Is laravel fractal still compatible with Lumen?

Support for Lumen was dropped in version 3 of the package, as noted in the README's upgrading section. For current versions, it's primarily aimed at Laravel, so using it in Lumen may require workarounds or alternative packages.

How to customize the JSON output format in laravel fractal?

Change the default serializer in the published config file, such as to JSON:API serializer. Use the `respond()` method with JSON encoding options (e.g., `JSON_PRETTY_PRINT`) for fine-grained control over the response format.

Laravel Fractal — Laravel API Data Transformation

What is Laravel Fractal?

Spatie's Laravel Fractal is a wrapper package that integrates the Fractal transformation library into Laravel and Lumen applications. It simplifies the process of transforming data, such as Eloquent models or arrays, into structured JSON outputs suitable for APIs. The package provides an expressive syntax and helper methods to reduce boilerplate code when building API responses.

Target Audience

Laravel and Lumen developers building RESTful or JSON APIs who need to transform complex data structures into consistent, well-formatted JSON responses. It's particularly useful for backend developers working on API-driven applications.

Value Proposition

Developers choose this package because it offers a more intuitive and Laravel-idiomatic way to use Fractal, with features like fluent chaining, direct Eloquent model transformation, and built-in response helpers. It reduces the complexity of raw Fractal usage while maintaining full flexibility.

An easy to use Fractal wrapper built for Laravel and Lumen applications

Use Cases

Best For

Transforming Eloquent query results into API-ready JSON structures
Building consistent JSON:API or RESTful endpoints in Laravel applications
Simplifying complex data transformations with an expressive, chainable syntax
Handling nested includes and excludes dynamically from request parameters
Reducing boilerplate code when formatting API responses
Integrating Fractal's transformation capabilities seamlessly into Laravel projects

Not Ideal For

Projects not using the Laravel framework, as the package is tightly integrated and offers no benefits outside of it.
Simple APIs with straightforward data structures that don't require complex transformations, making the overhead unnecessary.
Teams already leveraging Laravel's native API resources or other data transformation packages, as it adds redundant complexity.
Applications with strict dependency management policies that avoid external packages for core functionality.

Pros & Cons

Pros

Expressive Fluent Syntax

Offers a chainable interface that simplifies data transformation compared to raw Fractal usage, as demonstrated in the README's code examples with methods like `includeCharacters()`.

Seamless Laravel Integration

Directly works with Eloquent models and collections, allowing easy transformation of database results without extra steps, such as `Users::all()->transformWith(new UserTransformer())`.

Built-in Response Helpers

Includes a `respond()` method to return JSON responses with status codes and headers, streamlining API endpoint creation and reducing boilerplate code.

Auto-Configuration for Includes

Configurable handling of include and exclude parameters from request data via the config file, reducing manual parsing boilerplate for dynamic API responses.

Cons

External Dependency Overhead

Relies on the Fractal library, adding another layer that must be maintained and understood, which can complicate debugging and increase project complexity.

Breaking Changes History

The README documents several breaking changes between versions (e.g., v2 to v3 dropping Lumen support and config file renames), indicating potential upgrade challenges and maintenance headaches.

Limited Framework Support

Primarily designed for Laravel, with Lumen support dropped in later versions, making it unsuitable for other PHP frameworks or non-Laravel projects.

Frequently Asked Questions

What is Laravel Fractal?

Target Audience

Value Proposition

Use Cases

Best For

Transforming Eloquent query results into API-ready JSON structures
Building consistent JSON:API or RESTful endpoints in Laravel applications
Simplifying complex data transformations with an expressive, chainable syntax
Handling nested includes and excludes dynamically from request parameters
Reducing boilerplate code when formatting API responses
Integrating Fractal's transformation capabilities seamlessly into Laravel projects

Not Ideal For

Projects not using the Laravel framework, as the package is tightly integrated and offers no benefits outside of it.
Simple APIs with straightforward data structures that don't require complex transformations, making the overhead unnecessary.
Teams already leveraging Laravel's native API resources or other data transformation packages, as it adds redundant complexity.
Applications with strict dependency management policies that avoid external packages for core functionality.

Pros & Cons

Pros

Expressive Fluent Syntax

Offers a chainable interface that simplifies data transformation compared to raw Fractal usage, as demonstrated in the README's code examples with methods like `includeCharacters()`.

Seamless Laravel Integration

Directly works with Eloquent models and collections, allowing easy transformation of database results without extra steps, such as `Users::all()->transformWith(new UserTransformer())`.

Built-in Response Helpers

Includes a `respond()` method to return JSON responses with status codes and headers, streamlining API endpoint creation and reducing boilerplate code.

Auto-Configuration for Includes

Configurable handling of include and exclude parameters from request data via the config file, reducing manual parsing boilerplate for dynamic API responses.

Cons

External Dependency Overhead

Relies on the Fractal library, adding another layer that must be maintained and understood, which can complicate debugging and increase project complexity.

Breaking Changes History

The README documents several breaking changes between versions (e.g., v2 to v3 dropping Lumen support and config file renames), indicating potential upgrade challenges and maintenance headaches.

Limited Framework Support

Primarily designed for Laravel, with Lumen support dropped in later versions, making it unsuitable for other PHP frameworks or non-Laravel projects.

Frequently Asked Questions

Laravel Fractal

What is Laravel Fractal?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Laravel Fractal

What is Laravel Fractal?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?