Bincamp Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require azurespring/bincamp
   

   Ensure your composer.json includes "minimum-stability": "dev" if the package is in development.

2. Basic Setup Add the service provider in config/app.php:

   'providers' => [
       // ...
       AzureSpring\Bincamp\BincampServiceProvider::class,
   ],
   

3. First Use Case: Uploading a File

   use AzureSpring\Bincamp\Facades\Bincamp;
   
   $filePath = 'path/to/local/file.pdf';
   $binaryData = file_get_contents($filePath);
   
   $result = Bincamp::save($binaryData, 'file.pdf');
   // Returns a response with metadata (e.g., storage path, URL, or ID).
   

4. Retrieving a File

   $fileId = '123e4567-e89b-12d3-a456-426614174000';
   $binaryData = Bincamp::find($fileId);
   // Returns raw binary data or throws an exception if not found.
   

5. Configuration Publish the config file:

   php artisan vendor:publish --provider="AzureSpring\Bincamp\BincampServiceProvider" --tag="config"
   

   Customize config/bincamp.php (e.g., storage adapter, Azure Blob Storage credentials, or local filesystem paths).

Implementation Patterns

Core Workflows

1. Binary File Handling

   • Saving Files: Use Bincamp::save($binaryData, $filename, $options) for direct binary uploads.

     $options = [
         'contentType' => 'application/pdf',
         'metadata' => ['user_id' => 1, 'created_at' => now()],
     ];
     Bincamp::save($binaryData, 'document.pdf', $options);
     

   • Finding Files: Retrieve by ID (find($id)) or query with filters (if supported).

     $file = Bincamp::find('file-id-here');
     file_put_contents('downloads/' . $file['filename'], $file['data']);
     

2. Integration with Laravel

   • File Uploads in Controllers:

     public function upload(Request $request) {
         $request->validate(['file' => 'required|file']);
         $binaryData = file_get_contents($request->file('file')->getRealPath());
         $result = Bincamp::save($binaryData, $request->file('file')->getClientOriginalName());
         return response()->json($result);
     }
     

   • Storing File Metadata in Database: Use the returned metadata (e.g., storage_path, url) to link files to Eloquent models.

     $document = Document::create([
         'user_id' => auth()->id(),
         'file_id' => $result['id'],
         'storage_path' => $result['storage_path'],
     ]);
     

3. Storage Adapters

   • Local Filesystem: Default adapter (configured in config/bincamp.php).

     'driver' => 'local',
     'path' => storage_path('app/bincamp'),
     

   • Azure Blob Storage: Requires azure/azure-storage-blob and configuration:

     'driver' => 'azure',
     'connection' => 'azure',
     'container' => 'bincamp-container',
     

     Define the azure connection in config/filesystems.php.

4. Batch Operations

   • Bulk Upload:

     $files = ['file1.pdf', 'file2.jpg'];
     $results = collect($files)->map(function ($file) {
         return Bincamp::save(file_get_contents($file), basename($file));
     });
     

5. Events and Observers

   • Listen for file upload/download events (if the package supports them):

     // config/bincamp.php
     'events' => true,
     

     Publish event classes and create listeners:

     php artisan vendor:publish --provider="AzureSpring\Bincamp\BincampServiceProvider" --tag="events"
     

Gotchas and Tips

Pitfalls

1. Binary Data Handling

   • Corruption Risk: Ensure binary data is read/written correctly. Use file_get_contents() for local files and verify Content-Type headers for HTTP uploads.

     // Avoid:
     $binaryData = $request->file('file')->get(); // May not work as expected.
     // Use:
     $binaryData = file_get_contents($request->file('file'));
     

   • Memory Limits: Large files may exceed PHP’s memory_limit. Stream data for files >10MB:

     $stream = fopen($request->file('file'), 'r');
     $result = Bincamp::saveStream($stream, $filename);
     

2. Configuration Quirks

   • Missing Drivers: If using Azure Blob Storage, ensure the azure/azure-storage-blob package is installed and credentials are configured in config/filesystems.php.
   • Permissions: For local storage, verify the storage_path is writable:

     chmod -R 775 storage/app/bincamp
     

3. Debugging

   • Silent Failures: Enable logging in config/bincamp.php:

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

   • Exception Handling: Wrap calls in try-catch blocks:

     try {
         $file = Bincamp::find($id);
     } catch (\AzureSpring\Bincamp\Exceptions\FileNotFoundException $e) {
         Log::error('File not found: ' . $e->getMessage());
     }
     

4. Extension Points

   • Custom Storage Adapters: Implement AzureSpring\Bincamp\Contracts\StorageAdapter for new backends (e.g., S3, FTP).

     class CustomAdapter implements StorageAdapter {
         public function save($data, $filename, array $options) { ... }
         public function find($id) { ... }
     }
     

     Register the adapter in config/bincamp.php:

     'adapters' => [
         'custom' => \App\Adapters\CustomAdapter::class,
     ],
     

   • Middleware: Add middleware to validate/authenticate file operations:

     Bincamp::extend(function ($app) {
         $app->resolving('bincamp', function ($bincamp) {
             $bincamp->middleware(function ($request, $next) {
                 if (!$request->user()->can('upload_files')) {
                     throw new \Exception('Unauthorized');
                 }
                 return $next($request);
             });
         });
     });
     

5. Performance

   • Caching: Cache frequently accessed files in Redis or the filesystem:

     $cachedKey = "bincamp:{$id}";
     if (Cache::has($cachedKey)) {
         return Cache::get($cachedKey);
     }
     $file = Bincamp::find($id);
     Cache::put($cachedKey, $file, now()->addHours(1));
     return $file;
     

   • Async Processing: Use queues for large batch operations:

     UploadFileJob::dispatch($binaryData, $filename, $options);