Fractal Laravel Package

Getting Started

Start by installing the package via Composer and understanding Fractal’s core concepts: Transformer, Resource, Manager, and Serializer. The immediate use case is transforming Eloquent models or plain arrays into consistent JSON for APIs.

1. Run composer require league/fractal.
2. Create a Transformer class (extend TransformerAbstract) to define how your data maps to output.
3. Use Manager to create a Resource (e.g., new Item($model, new YourTransformer())) and serialize with toJson() or toArray().
4. Choose a serializer (ArraySerializer, DataArraySerializer, or JsonApiSerializer) based on your API format needs.
   First example: transforming a single User model into JSON without exposing internal DB fields or inconsistent types.

Implementation Patterns

• Transformers as Contracts: Define transform() to return a standardized schema—use include methods to conditionally embed relationships (e.g., includePosts() for /users?include=posts).
• Smart Include Syntax: Parse URL include parameters with Manager::parseIncludes('posts:limit(10):order(-created_at)'), enabling flexible, client-controlled expansion of nested data.
• Pagination Support: Inject any framework paginator (Laravel, Doctrine, Pagerfanta) via Collection::setPaginator(), and Fractal auto-generates pagination metadata and links in JSON-API/Array formats.
• Fieldsets & Sparse Fields: Use parseFieldsets() to let clients request only needed fields (?fields[users]=name,email), reducing payload size.
• Null & Primitive Resources: Serialize null values with Resource::null() or scalars via Primitive—avoiding null collapsing in output.
• Serializer Customization: Extend serializers for bespoke needs (e.g., adding custom links, altering meta structure), or mix in hooks like shouldSerializeNull().

Gotchas and Tips

• Scope Clearing in v0.21+: After transformation, getCurrentScope() returns null. Capture it within the transformer (e.g., in transform()) if needed—otherwise, rely on include* methods that receive scope parameters.
• Meta vs Attributes Confusion: setMeta() adds top-level metadata, while attributes (in transform()) contain resource fields. In JSON-API, attributes must be an object—not an array—even if empty.
• Paginator Gotchas: For collections, always call setPaginator() before serialization. Non-paginated collections omit pagination metadata unless you explicitly add it.
• Type Casting is Manual: Fractal doesn’t auto-cast types—explicitly convert in transform() (e.g., (bool) $model->active) to avoid inconsistent JSON booleans/strings.
• Include Constraints: Parameter syntax like limit(5) is parsed by your transformer logic—not Fractal itself. Validate or sanitize these if来自 untrusted clients (e.g., enforce max limits).
• Memory Leaks Avoidance: The library now unsets internal scope references post-transformation (v0.21), but avoid storing scopes in long-lived closures or static properties.