Fractalistic Laravel Package

Getting Started

Start by installing the package via Composer: composer require spatie/fractalistic. Import Spatie\Fractalistic\Fractal and begin transforming data with the fluent API. The simplest use case is transforming a simple array:

Fractal::create($books, new BookTransformer())->toArray();

For quick inline transformations, use a closure:

Fractal::create($books, fn($book) => ['id' => $book['id']])->toArray();

If using Laravel, prefer laravel-fractal instead — this package targets non-Laravel or lightweight use cases.

Implementation Patterns

• Transformer patterns: Pass transformers as instances, classes (Transformer::class), or closures to transformWith() or directly to collection()/item().
• Includes/excludes: Use method chaining like ->includeCharacters() and ->excludePublisher() for clean, readable relationship inclusion — or fall back to ->parseIncludes(['characters']) for dynamic cases.
• Serialization control: Apply ->serializeWith(new ArraySerializer()) to remove the default data wrapper; configure default serializer globally via config if needed.
• Pagination & cursors: Use with Fractal adapters (IlluminatePaginatorAdapter, Cursor) for API pagination metadata — especially critical for JsonApiSerializer.
• Short syntax: For one-liners, Fractal::create($data, $transformer, $serializer)->toJson() covers most simple cases.

Gotchas and Tips

• Framework confusion: This is not a Laravel-only tool; it’s framework-agnostic. Laravel users should use laravel-fractal, which builds on this package.
• Recursion limits: Default recursion depth is 10; use ->limitRecursion(5) to prevent infinite loops in deeply nested includes — especially when transforming Eloquent relations with bi-directional loading.
• Empty collections: Prior to v2.3.1, empty arrays could break; ensure you're on v2.3.1+ if using empty collections.
• Resource naming: With serializers that wrap in data, use ->withResourceName('books') (v2.11+) to customize the key — not all serializers respect this, e.g., ArraySerializer ignores wrapper keys.
• Serializer compatibility: ArraySerializer flattens output ([['id'=>1]] instead of ['data' => [['id'=>1]]]), but JsonApiSerializer expects proper pagination/cursor setup to emit links and meta.
• NullResource support: For 204 No Content responses, use Fractal::create()->null() or set null() resource before transformation to avoid errors.
• PHP 8.1/8.2+: Fully supported as of recent releases — no special config needed.