Bincamp Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require azurespring/bincamp-bundle
   

   Register the bundle in config/app.php under providers:

   AzureSpring\BincampBundle\BincampBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="AzureSpring\BincampBundle\BincampServiceProvider"
   

   Update config/bincamp.php with your Azure Blob Storage credentials (connection string, container name, etc.).

3. First Use Case: Uploading a File Inject the BincampService into a controller or service:

   use AzureSpring\BincampBundle\Service\BincampService;
   
   public function uploadFile(Request $request, BincampService $bincamp)
   {
       $file = $request->file('file');
       $path = $bincamp->upload($file, 'user-uploads'); // 'user-uploads' is the blob container
       return response()->json(['path' => $path]);
   }
   

4. First Use Case: Retrieving a File

   public function downloadFile(BincampService $bincamp)
   {
       $blobName = 'user-uploads/example.pdf';
       $stream = $bincamp->download($blobName);
       return response()->stream(function () use ($stream) {
           fpassthru($stream);
       }, 200, [
           'Content-Type' => 'application/pdf',
           'Content-Disposition' => 'attachment; filename="example.pdf"',
       ]);
   }
   

Implementation Patterns

Core Workflows

1. File Uploads

   • Single File Upload:

     $path = $bincamp->upload($file, $container, ['metadata' => ['user_id' => 1]]);
     

   • Chunked Uploads (for large files):

     $uploadId = $bincamp->createBlockBlob($container, $blobName);
     $bincamp->uploadBlock($uploadId, $chunk, $index);
     $bincamp->commitBlockBlob($uploadId);
     

2. File Retrieval

   • Streaming Downloads (memory-efficient):

     $stream = $bincamp->download($blobName);
     

   • Direct URL Generation (for client-side downloads):

     $sasUrl = $bincamp->generateSasUrl($blobName, '+r', 3600); // Valid for 1 hour
     

3. File Management

   • List Blobs in Container:

     $blobs = $bincamp->listBlobs($container, 'prefix-');
     

   • Delete Blob:

     $bincamp->deleteBlob($blobName);
     

4. Metadata and Properties

   • Set/Get Metadata:

     $bincamp->setMetadata($blobName, ['custom_key' => 'value']);
     $metadata = $bincamp->getMetadata($blobName);
     

Integration Tips

• Laravel Filesystem Integration: Use the BincampAdapter to integrate with Laravel's filesystem:

  $filesystem = Storage::disk('azure');
  $filesystem->put('remote-file.txt', 'contents');
  

  Configure in config/filesystems.php:

  'azure' => [
      'driver' => 'azure',
      'container' => 'my-container',
  ],
  

• Event Handling: Bind to blob events (e.g., upload completion) using Laravel's event system:

  event(new \AzureSpring\BincampBundle\Events\BlobUploaded($blobName, $metadata));
  

• Validation: Validate file types/sizes before upload:

  $request->validate([
      'file' => 'required|file|mimes:pdf,docx|max:10240', // 10MB
  ]);
  

Gotchas and Tips

Common Pitfalls

1. Connection Issues

   • Ensure the connection string in config/bincamp.php is correct and has the right permissions.
   • Test connectivity with:

     $bincamp->testConnection();
     

   • Error: StorageException often indicates invalid credentials or network issues.

2. Blob Naming Collisions

   • Azure Blob Storage requires globally unique names within a container.
   • Use UUIDs or hashed filenames:

     $blobName = 'uploads/' . Str::uuid() . '.' . $file->getClientOriginalExtension();
     

3. Large File Timeouts

   • Chunked uploads are required for files > 4MB (default block size).
   • Increase PHP's max_execution_time or use queue jobs for large uploads:

     UploadLargeFileJob::dispatch($file, $container)->onQueue('uploads');
     

4. SAS Token Expiry

   • SAS URLs expire by default after 1 hour. Adjust the expiry in generateSasUrl():

     $sasUrl = $bincamp->generateSasUrl($blobName, '+r', 86400); // 24 hours
     

5. Case Sensitivity

   • Blob names are case-sensitive in Azure. Normalize names:

     $blobName = strtolower($blobName);
     

Debugging Tips

• Enable Logging: Add to config/bincamp.php:

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

  Logs will appear in storage/logs/laravel.log.

• Check Blob Existence:

  if (!$bincamp->blobExists($blobName)) {
      // Handle missing blob
  }
  

• Retry Failed Operations: Use Laravel's retry helper for transient failures:

  retry(5, function () use ($bincamp, $blobName) {
      $bincamp->download($blobName);
  });
  

Extension Points

1. Custom Storage Accounts Override the default connection in config:

   'connections' => [
       'primary' => [
           'connection_string' => env('AZURE_STORAGE_CONNECTION_STRING'),
           'container' => env('AZURE_CONTAINER'),
       ],
       'backup' => [
           'connection_string' => env('AZURE_BACKUP_CONNECTION_STRING'),
           'container' => env('AZURE_BACKUP_CONTAINER'),
       ],
   ],
   

   Switch dynamically:

   $bincamp->setConnection('backup');
   

2. Middleware for File Access Create middleware to validate SAS tokens or user permissions:

   public function handle($request, Closure $next)
   {
       $blobName = $request->route('blob');
       if (!$bincamp->validateSasToken($blobName, $request->query('token'))) {
           abort(403);
       }
       return $next($request);
   }
   

3. Custom Metadata Handlers Extend the BincampService to auto-populate metadata:

   $bincamp->extend(function ($service) {
       $service->beforeUpload(function ($file, $container, $options) {
           $options['metadata']['uploaded_by'] = auth()->id();
           return $options;
       });
   });
   

4. Fallback Storage Implement a fallback to local storage if Azure is unavailable:

   try {
       $path = $bincamp->upload($file, $container);
   } catch (\Exception $e) {
       $path = Storage::disk('local')->putFile('fallback', $file);
   }