Luigis Box Bundle Laravel Package

Getting Started

Install via Composer:

composer require answear/luigis-box-bundle

Publish the configuration (if needed):

php artisan vendor:publish --provider="Answear\LuigisBoxBundle\LuigisBoxServiceProvider"

The package now includes a GUID field in API responses (added in v5.3.0), which can be useful for client-side tracking or unique identifier needs. Check the default response structure in config/luigis-box.php for the new field.

First Use Case: Enable GUIDs in responses by setting:

'include_guid' => true,

in the config. Verify by inspecting API responses—each resource will now include a guid field.

Implementation Patterns

API Response Handling

The GUID field is automatically appended to all serializable responses (e.g., Eloquent models, collections). Use this for:

• Client-side state management (e.g., React/Vue keys).
• Analytics tracking (e.g., event('track', ['guid' => $response->guid])).
• Merge/upsert logic (e.g., Model::updateOrCreate(['guid' => $request->guid], [...])).

Customization

Override the GUID generation logic by binding a custom generator to the container:

$this->app->bind(\Answear\LuigisBoxBundle\Contracts\GuidGenerator::class, function () {
    return new \YourApp\CustomGuidGenerator();
});

Integration with Resources

Extend Laravel’s JsonResource to explicitly include the GUID:

public function toArray($request)
{
    return array_merge(parent::toArray($request), [
        'guid' => $this->resource->guid ?? strtolower(Ramsey\Uuid\Uuid::uuid4()->toString()),
    ]);
}

Gotchas and Tips

Pitfalls

1. Performance Impact: GUID generation (default: UUIDv4) adds ~1ms per request. Cache the generator if generating GUIDs outside API responses:

   $guid = app(\Answear\LuigisBoxBundle\Contracts\GuidGenerator::class)->generate();
   

2. Database Storage: The GUID is not stored in the database by default. If you need persistence, add a guid column to your tables and hydrate it via model events:

   protected static function booted()
   {
       static::creating(function ($model) {
           $model->guid = strtolower(Ramsey\Uuid\Uuid::uuid4()->toString());
       });
   }
   

3. Deprecation Risk: The GUID field is new (v5.3.0) and may evolve. Pin the package version in composer.json if relying on this feature.

Debugging

• Missing GUIDs? Verify include_guid is true in config and that your response is using the bundle’s default serializer (e.g., JsonResource).
• Duplicate GUIDs? Ensure your custom generator implements GuidGenerator::generate() and returns unique values.

Extension Points

• Custom Fields: Extend the response structure by publishing and modifying the bundle’s view templates (e.g., resources/views/vendor/luigis-box/partials/response.blade.php).
• Validation: Validate GUIDs in requests using Laravel’s built-in validation:

  $request->validate(['guid' => 'uuid']);