Lumen Fractal Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require gergonzalez/lumen-fractal
   

   Add the service provider to bootstrap/app.php:

   $app->register(\Gergonzalez\LumenFractal\FractalServiceProvider::class);
   

2. First Use Case Define a simple transformer (e.g., app/Transformers/UserTransformer.php):

   namespace App\Transformers;
   
   use League\Fractal\TransformerAbstract;
   
   class UserTransformer extends TransformerAbstract
   {
       public function transform($user)
       {
           return [
               'id' => $user->id,
               'name' => $user->name,
               'email' => $user->email,
           ];
       }
   }
   

   Use it in a Lumen route:

   use Gergonzalez\LumenFractal\Facades\Fractal;
   
   Route::get('/users/{id}', function ($id) {
       $user = User::findOrFail($id);
       return Fractal::item(new UserTransformer(), $user)->toArray();
   });
   

3. Key Files to Review

   • config/fractal.php (default config, if provided).
   • app/Transformers/ (custom transformers).
   • Gergonzalez\LumenFractal\Facades\Fractal (main facade).

Implementation Patterns

Common Workflows

1. API Resource Transformation Use Fractal::item() for single resources or Fractal::collection() for lists:

   // Single resource
   return Fractal::item(new PostTransformer(), $post)->toArray();
   
   // Collection
   return Fractal::collection(new PostTransformer(), Post::all())->toArray();
   

2. Nested Transformations Define relationships in transformers:

   class UserTransformer extends TransformerAbstract
   {
       public function transform($user)
       {
           return [
               'id' => $user->id,
               'posts' => $this->lineItems($user->posts, new PostTransformer()),
           ];
       }
   }
   

3. Customizing Serialization Override default serialization (e.g., JSON) via config or facade:

   Fractal::parseIncludes($request->input('include', []));
   return Fractal::item($transformer, $model)->toArray();
   

4. Middleware Integration Attach Fractal logic to middleware for consistent responses:

   $app->middleware([
       \Gergonzalez\LumenFractal\Middleware\FractalMiddleware::class,
   ]);
   

Integration Tips

• Lumen Middleware: Extend FractalMiddleware to add pre-processing (e.g., auth checks).
• Testing: Mock Fractal facade in PHPUnit:

  $this->app->instance(\Gergonzalez\LumenFractal\Facades\Fractal::class, MockFractal::new());
  

• Performance: Cache transformers or responses for high-traffic endpoints.

Gotchas and Tips

Pitfalls

1. Facade Initialization Ensure the FractalServiceProvider is registered before using the facade. Lumen’s lazy loading may cause Undefined class errors if misconfigured.

2. Transformer Autoloading The package doesn’t auto-discover transformers. Manually register them in FractalServiceProvider or use a naming convention (e.g., *Transformer).

3. Lumen vs. Laravel Quirks

   • Lumen lacks Laravel’s RouteServiceProvider, so bind transformers manually:

     $app->singleton(UserTransformer::class);
     

   • Avoid Route::resource(); use explicit routes for fine-grained Fractal control.

4. Error Handling Fractal throws exceptions for invalid includes or missing transformers. Wrap calls in try-catch:

   try {
       return Fractal::item($transformer, $model)->toArray();
   } catch (\League\Fractal\Manager::class $e) {
       return response()->json(['error' => $e->getMessage()], 400);
   }
   

Debugging Tips

• Check Includes: Use Fractal::parseIncludes() to debug malformed include query params.
• Transformer Output: Temporarily dump raw data:

  dd($transformer->transform($model));
  

• Config Overrides: Override config/fractal.php to adjust default behavior (e.g., default_includes).

Extension Points

1. Custom Serializers Extend League\Fractal\Serializer\SerializerAbstract and bind it:

   $app->singleton(\League\Fractal\Serializer\SerializerAbstract::class, CustomSerializer::class);
   

2. Resource Naming Dynamically set resource keys (e.g., for polymorphic relationships):

   Fractal::item($transformer, $model, 'dynamic_key')->toArray();
   

3. Event Listeners Listen for fractal.transforming events to modify payloads:

   $app->on('fractal.transforming', function ($payload) {
       $payload->setData(['custom_field' => true]);
   });