Resource Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blast-project/resource-bundle
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Blast\ResourceBundle\ResourceBundleServiceProvider::class,
   ],
   

2. Publish Config

   php artisan vendor:publish --provider="Blast\ResourceBundle\ResourceBundleServiceProvider" --tag="config"
   

   This generates config/resource-bundle.php with default settings.

3. First Use Case: Temporary File Storage

   use Blast\ResourceBundle\Facades\ResourceBundle;
   
   // Store a temporary resource (e.g., uploaded file)
   $resource = ResourceBundle::store('my-temp-file.txt', file_get_contents('path/to/file'));
   
   // Retrieve later (valid until expiration)
   $content = ResourceBundle::retrieve($resource->getId());
   

Implementation Patterns

Core Workflows

1. Temporary Resource Management

   • Upload Handling: Store files during multi-step processes (e.g., form uploads before validation).

     $tempId = ResourceBundle::store('user_avatar.jpg', $request->file('avatar')->get());
     // Process form...
     if ($valid) {
         $user->avatar = ResourceBundle::retrieve($tempId)->getPath();
     }
     

   • Cleanup: Automatically expire resources after config('resource-bundle.ttl') (default: 1 hour).

2. Integration with Laravel Features

   • Filesystem: Use Laravel’s filesystem drivers (e.g., local, s3) via config:

     'disk' => 's3', // Override default 'local'
     

   • Events: Listen for ResourceBundle\Events\ResourceStored/ResourceExpired:

     Event::listen(ResourceExpired::class, function ($event) {
         Log::debug("Resource {$event->id} expired");
     });
     

3. Bulk Operations

   • Store multiple resources in a batch:

     $batch = ResourceBundle::batchStore([
         'file1' => file_get_contents('path1'),
         'file2' => file_get_contents('path2'),
     ]);
     // Retrieve by key: $batch['file1']->getContent()
     

4. Custom Metadata

   • Attach metadata during storage:

     $resource = ResourceBundle::store('data.json', $data, [
         'user_id' => auth()->id(),
         'purpose' => 'profile_export',
     ]);
     // Retrieve metadata: $resource->getMetadata()
     

Gotchas and Tips

Pitfalls

1. TTL Misconfiguration

   • Default TTL (1 hour) may be too short for long-running processes. Adjust in config:

     'ttl' => 60 * 24, // 24 hours
     

   • Debug Tip: Check expiration with:

     $resource->isExpired(); // Returns bool
     

2. Disk Space Risks

   • Unbounded storage can fill disk. Use max_size config to limit total storage:

     'max_size' => 100 * 1024 * 1024, // 100MB
     

   • Warning: The package lacks built-in cleanup for max_size; implement a cron job to prune expired resources:

     php artisan resource:bundle:prune
     

3. Race Conditions

   • Retrieving an expired resource throws ResourceNotFoundException. Handle gracefully:

     try {
         $content = ResourceBundle::retrieve($id);
     } catch (ResourceNotFoundException $e) {
         // Fallback logic
     }
     

4. Filesystem Permissions

   • Ensure the configured disk has write permissions. Test with:

     php artisan storage:link
     

Tips

1. Naming Conventions

   • Use UUIDs for IDs to avoid collisions:

     $resource = ResourceBundle::store('data.json', $data, [
         'id' => Str::uuid()->toString(),
     ]);
     

2. Testing

   • Mock the bundle in tests by overriding the TTL:

     $this->app->bind(ResourceBundle::class, function () {
         return new ResourceBundle(config(['resource-bundle.ttl' => 1]));
     });
     

3. Extension Points

   • Custom Storage: Implement Blast\ResourceBundle\Contracts\ResourceStorage for databases or cloud storage.
   • Events: Extend with ResourceBundle\Events\ResourceCustomEvent for domain-specific logic.

4. Logging

   • Enable debug logging in config:

     'debug' => env('APP_DEBUG', false),
     

   • View logs at storage/logs/laravel.log for storage/retrieval events.

5. Performance

   • For high-throughput systems, disable metadata logging:

     'log_metadata' => false,