File Distribution Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aboutcoders/file-distribution
   

   Add the service provider to config/app.php:

   Aboutcoders\FileDistribution\FileDistributionServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Aboutcoders\FileDistribution\FileDistributionServiceProvider"
   

   Locate the config at config/file-distribution.php.

3. First Use Case Distribute a file to multiple users via email:

   use Aboutcoders\FileDistribution\Facades\FileDistribution;
   
   $filePath = storage_path('app/large-report.pdf');
   $recipients = ['user1@example.com', 'user2@example.com'];
   
   FileDistribution::send($filePath, $recipients);
   

Implementation Patterns

Core Workflows

1. File Distribution via Email

   FileDistribution::send(
       $filePath,
       $recipients,
       ['subject' => 'Your Document', 'message' => 'Please find attached']
   );
   

   • Supports custom email templates (publish resources/views/vendor/file-distribution/email.blade.php).
   • Attachments are automatically chunked for large files (configurable in max_chunk_size).

2. Queue-Based Distribution Use Laravel queues to avoid timeouts for large files:

   FileDistribution::queueSend($filePath, $recipients);
   

   • Requires queue:work to be running.

3. Custom Storage Integration Extend for S3, Dropbox, etc.:

   FileDistribution::extend('s3', function ($app) {
       return new S3FileDistributor($app['aws']);
   });
   

Integration Tips

• Laravel Notifications: Combine with Notifiable for user-specific emails:

  $user->notify(new FileDistributionNotification($filePath));
  

• Events: Listen for FileDistributionSent events to log or audit:

  event(new FileDistributionSent($filePath, $recipients));
  

• API Endpoints: Secure a route for file distribution:

  Route::post('/distribute', function (Request $request) {
      $this->authorize('distribute-files');
      FileDistribution::send($request->file, $request->recipients);
  });
  

Gotchas and Tips

Pitfalls

1. Memory Limits

   • Large files (>100MB) may hit PHP memory limits. Use queueSend() or chunking:

     'max_chunk_size' => 50 * 1024 * 1024, // 50MB
     

   • Increase memory_limit in php.ini temporarily for testing.

2. Email Attachment Limits

   • Some email providers (e.g., Gmail) cap attachments at 25MB. Test with your recipients’ providers.

3. File Permissions

   • Ensure the web server user (e.g., www-data) has read access to distributed files:

     chmod -R 755 storage/app/files/
     

Debugging

• Log Distribution Events Enable logging in config/file-distribution.php:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

• Check Queue Jobs For queued distributions, inspect jobs with:

  php artisan queue:list
  php artisan queue:work --once
  

Extension Points

1. Custom Distributors Implement Aboutcoders\FileDistribution\Contracts\Distributor:

   class SlackDistributor implements Distributor {
       public function distribute($filePath, array $recipients) { ... }
   }
   

   Register via:

   FileDistribution::extend('slack', function () { return new SlackDistributor(); });
   

2. Pre/Post Hooks Use events to modify behavior:

   FileDistribution::beforeSend(function ($event) {
       if ($event->file->isLarge()) {
           $event->setChunkSize(30 * 1024 * 1024);
       }
   });
   

3. Override Templates Publish and modify:

   php artisan vendor:publish --tag=file-distribution-views
   

   Edit resources/views/vendor/file-distribution/email.blade.php.