Attach File Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require carloschininin/attach-file-bundle
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="CarlosChininin\AttachFileBundle\AttachFileServiceProvider"
   

2. Basic Usage Register the service provider in config/app.php:

   'providers' => [
       // ...
       CarlosChininin\AttachFileBundle\AttachFileServiceProvider::class,
   ],
   

3. First Use Case: File Upload Use the AttachFile facade to handle uploads:

   use CarlosChininin\AttachFileBundle\Facades\AttachFile;
   
   $file = AttachFile::upload('file_input_name', 'path/to/storage');
   

Implementation Patterns

Core Workflows

1. Handling File Uploads

   • Single File Upload:

     $file = AttachFile::upload('file_field', 'uploads');
     // Returns an array with metadata (path, filename, etc.)
     

   • Multiple File Upload:

     $files = AttachFile::uploadMultiple('files_field', 'uploads');
     // Returns a collection of file metadata
     

2. Integration with Forms

   • Use in Laravel controllers or Form Requests:

     public function store(Request $request) {
         $file = AttachFile::upload($request->file('document'), 'documents');
         // Process file metadata...
     }
     

3. Validation and Sanitization

   • Leverage built-in validation (if available) or extend:

     $file = AttachFile::upload('file_field', 'uploads', [
         'max_size' => '2mb',
         'allowed_types' => ['pdf', 'docx'],
     ]);
     

4. Storing Metadata

   • Attach file metadata to Eloquent models:

     $user->files()->create([
         'path' => $file['path'],
         'original_name' => $file['original_name'],
     ]);
     

Gotchas and Tips

Common Pitfalls

1. Storage Configuration

   • Ensure filesystems in config/filesystems.php is properly set up (e.g., local, s3).
   • Default storage disk is not explicitly defined in the package; verify in config/attach-file.php (if published).

2. File Naming Collisions

   • The package may not handle duplicate filenames by default. Use a custom naming strategy:

     $file = AttachFile::upload('file_field', 'uploads', [
         'naming_strategy' => function ($originalName) {
             return Str::uuid() . '.' . pathinfo($originalName, PATHINFO_EXTENSION);
         },
     ]);
     

3. Missing Facade

   • If AttachFile facade isn’t autoloaded, manually register it in AppServiceProvider:

     Facades\AttachFile::class => CarlosChininin\AttachFileBundle\Facades\AttachFile::class,
     

Debugging Tips

• Check Uploaded Files Verify files are being received in the request:

  dd($request->file('field_name')->isValid());
  

• Log File Metadata Debug file paths and storage issues:

  $file = AttachFile::upload('file_field', 'uploads');
  \Log::info('Uploaded file:', $file);
  

Extension Points

1. Custom Storage Logic Override the default storage handler by binding a custom service:

   $this->app->bind('attach-file.storage', function () {
       return new CustomStorageHandler();
   });
   

2. Event Listeners Listen for file upload events (if the package emits them):

   // Example (hypothetical event)
   event(new FileUploaded($file));
   

3. Middleware for Authenticated Uploads Restrict uploads to authenticated users:

   Route::middleware(['auth'])->group(function () {
       // Upload routes here
   });
   

Configuration Quirks

• Default Disk The package may default to public disk. Override in config/attach-file.php:

  'disk' => 's3',
  

• Permissions Ensure the storage directory has write permissions:

  chmod -R 775 storage/app/uploads