php-open-source-saver/fractal

Handle the output of complex data structures ready for API output.

v0.22.0 2025-01-12 05:41 UTC

Requires

• php: >=8.1

Requires (Dev)

• doctrine/orm: ^2.5
• illuminate/contracts: ~10.0
• mockery/mockery: ^1.3
• pagerfanta/pagerfanta: ~1.0.0
• phpstan/phpstan: ^1.4
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ~3.4
• vimeo/psalm: ^4.22|^5.20
• zendframework/zend-paginator: ~2.3

Suggests

• illuminate/pagination: The Illuminate Pagination component.
• pagerfanta/pagerfanta: Pagerfanta Paginator
• zendframework/zend-paginator: Zend Framework Paginator

MIT

• Phil Sturgeon
• Max Snow

• json
• rest
• api
• laravel
• league

README

Credits

This repository is a fork from original thephpleague/fractal, we decided to make an independent fork due to the lack of updates to the original package, and lack of a process for volunteers to become maintainers within the php league ecosystem of packages.

Migrating from thephpleague/fractal

This uses different namespace to thephpleague/fractal, but overall, provides the same API, that makes migration to this repository pretty easy:

1. Run composer remove thephpleague/fractal

   Info An error will appear because the package is still in use, ignore it.

2. Replace all the occurrences of League\Fractal with PHPOpenSourceSaver\Fractal.

   Tip: You can use Find and Replace feature of your IDE. Try it with Ctrl + Shift + R

3. Run composer require php-open-source-saver/fractal

Notes

Fractal provides a presentation and transformation layer for complex data output, the like found in RESTful APIs, and works really well with JSON. Think of this as a view layer for your JSON/YAML/etc.

When building an API it is common for people to just grab stuff from the database and pass it to json_encode(). This might be passable for "trivial" APIs but if they are in use by the public, or used by mobile applications then this will quickly lead to inconsistent output.

Goals

• Create a protective shield between source data and output, so schema changes do not affect users
• Systematic type-casting of data, to avoid foreach()ing through and (bool)ing everything
• Include (a.k.a embedding, nesting or side-loading) relationships for complex data structures
• Work with standards like HAL and JSON-API but also allow custom serialization
• Support the pagination of data results, for small and large data sets alike
• Generally ease the subtle complexities of outputting data in a non-trivial API

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Install

Via Composer

$ composer require php-open-source-saver

Requirements

The following versions of PHP are supported by this version:

>= PHP 8.1

Documentation

Fractal has full documentation, powered by Jekyll.

Contribute to this documentation in the gh-pages branch.

Testing

$ phpunit

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Maintainers

• Max Snow

Credits

• Graham Daniels
• Andrew Willis
• Phil Sturgeon
• Korvin Szanto
• Matt Trask
• All Contributors

Reporting a Vulnerability

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.