Relay Blob Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require dbp/relay-blob-bundle dbp/relay-blob-connector-filesystem-bundle
   

   (Replace filesystem with your preferred connector, e.g., s3, gcs.)

2. Configure Bundles Add to config/bundles.php before DbpRelayCoreBundle:

   Dbp\Relay\BlobBundle\DbpRelayBlobBundle::class => ['all' => true],
   

3. Configure Storage Define buckets in config/packages/dbp_relay_blob.yaml:

   dbp_relay_blob:
       buckets:
           default:
               connector: filesystem
               options:
                   directory: "%kernel.project_dir%/public/uploads"
   

4. First Use Case: Upload a File Use the API endpoint (auto-generated by the bundle) to upload a file:

   curl -X POST \
     -F "file=@/path/to/file.jpg" \
     http://your-app/_relay/blob/upload?bucket=default
   

   (Response includes an ephemeral URL for the file.)

Implementation Patterns

Core Workflows

1. Bucket-Based Storage

   • Pattern: Organize files by "buckets" (e.g., user_uploads, media_assets).
   • Example:

     buckets:
         user_uploads:
             connector: s3
             options:
                 bucket: "my-app-uploads"
                 region: "eu-central-1"
     

2. Signed Requests for Security

   • Pattern: Generate signed URLs for client-side uploads (e.g., via JavaScript SDKs like minio or aws-sdk).
   • Example:

     use Dbp\Relay\BlobBundle\Service\BlobService;
     
     $blobService = $this->container->get(BlobService::class);
     $signedUrl = $blobService->generateSignedUploadUrl('default', 'file.jpg', 3600);
     

3. Integration with Laravel Controllers

   • Pattern: Use the bundle’s services in controllers for file handling.
   • Example:

     use Dbp\Relay\BlobBundle\Service\BlobService;
     
     public function upload(Request $request, BlobService $blobService) {
         $file = $request->file('file');
         $upload = $blobService->upload($file, 'default');
         return response()->json(['url' => $upload->getUrl()]);
     }
     

4. File Metadata Management

   • Pattern: Attach metadata (e.g., user_id, content_type) to blobs via the API.
   • Example:

     curl -X POST \
       -F "file=@image.jpg" \
       -F "metadata[user_id]=123" \
       http://your-app/_relay/blob/upload?bucket=default
     

5. Event-Driven Extensions

   • Pattern: Listen to blob events (e.g., blob.uploaded) to trigger post-processing (e.g., image thumbnails).
   • Example:

     // In a service provider
     $this->eventDispatcher->addListener(
         BlobEvents::UPLOADED,
         function (BlobUploadedEvent $event) {
             // Process $event->getBlob()
         }
     );
     

Gotchas and Tips

Pitfalls

1. Connector Dependency

   • Issue: The bundle requires a connector (e.g., filesystem, s3). Forgetting to install one will throw ServiceNotFoundException.
   • Fix: Always install the connector bundle (e.g., dbp/relay-blob-connector-s3-bundle).

2. Bucket Configuration Overrides

   • Issue: Bucket options in config/packages/dbp_relay_blob.yaml are merged, not replaced. Incorrect merging can lead to silent failures.
   • Fix: Use explicit keys or debug with var_dump($this->container->getParameter('dbp_relay_blob.buckets')).

3. Ephemeral URLs

   • Issue: Ephemeral URLs expire (default: 1 hour). Clients may receive 403 Forbidden if not refreshed.
   • Fix: Regenerate URLs server-side or extend expiry via generateSignedUploadUrl($bucket, $filename, $expirySeconds).

4. File Size Limits

   • Issue: The bundle inherits PHP’s upload_max_filesize and post_max_size. Large files may fail silently.
   • Fix: Adjust php.ini or use chunked uploads (e.g., Tus protocol via a custom connector).

5. CORS Restrictions

   • Issue: Direct uploads from browsers may fail due to CORS if the API endpoint lacks proper headers.
   • Fix: Configure CORS in your web server (e.g., Nginx) or middleware:

     $response->headers->set('Access-Control-Allow-Origin', '*');
     

Debugging Tips

1. Enable Verbose Logging Add to config/packages/monolog.yaml:

   handlers:
       relay_blob:
           type: stream
           path: "%kernel.logs_dir%/relay_blob.log"
           level: debug
           channels: ["relay_blob"]
   

   Then log events in your connector:

   $this->logger->debug('Uploading file', ['bucket' => $bucket, 'file' => $file->getClientOriginalName()]);
   

2. Check Connector-Specific Errors

   • Filesystem: Verify directory permissions (chmod -R 775 %kernel.project_dir%/public/uploads).
   • S3/GCS: Ensure credentials and bucket names are correct in the connector config.

3. Validate API Responses The bundle returns JSON responses with a success flag. Always check:

   {
       "success": true,
       "data": {
           "url": "https://.../file.jpg",
           "metadata": { ... }
       }
   }
   

Extension Points

1. Custom Connectors

   • How: Implement Dbp\Relay\BlobBundle\Connector\BlobConnectorInterface and register it as a service.
   • Example:

     // src/Connector/CustomConnector.php
     class CustomConnector implements BlobConnectorInterface {
         public function upload(UploadedFile $file, array $options) { ... }
         public function generateUrl(string $filename, array $options) { ... }
     }
     

2. Middleware for Pre/Post-Processing

   • How: Bind to KernelEvents::REQUEST or BlobEvents::UPLOADED to modify requests/responses.
   • Example:

     $event->getResponse()->headers->set('X-Custom-Header', 'value');
     

3. Database Backing for Metadata

   • How: Extend the Blob entity (if using Doctrine) to add custom fields.
   • Example:

     // src/Entity/ExtendedBlob.php
     class ExtendedBlob extends Blob {
         /**
          * @ORM\Column(type="string", nullable=true)
          */
         private $customField;
     }