Fileman Laravel Package

Getting Started

First Steps

1. Installation

   composer require darvinstudio/fileman
   

   • Verify the package is autoloaded (check composer.json and vendor/).

2. Basic Usage

   • The package likely provides a facade or helper class for common file operations.
   • Start with the core methods (e.g., Fileman::upload(), Fileman::delete(), Fileman::move()).
   • Example:

     use Darvinstudio\Fileman\Facades\Fileman;
     
     $path = Fileman::upload('path/to/file', 'destination/dir');
     

3. Configuration

   • Check for a config file (e.g., config/fileman.php) and update storage paths, disk settings, or permissions.
   • Defaults may assume local disk; override if using S3, FTP, etc.

4. First Use Case

   • Handle file uploads in a Laravel controller:

     public function upload(Request $request) {
         $file = $request->file('file');
         $path = Fileman::upload($file->getRealPath(), 'uploads/');
         return response()->json(['path' => $path]);
     }
     

Implementation Patterns

Common Workflows

1. File Uploads with Validation

   • Combine with Laravel’s Validator or FormRequest:

     $request->validate(['file' => 'required|mimes:jpg,png|max:2048']);
     $path = Fileman::upload($request->file('file'), 'uploads/validated/');
     

2. Batch Operations

   • Process multiple files (e.g., from a directory or request array):

     $files = $request->file('files');
     foreach ($files as $file) {
         Fileman::upload($file, 'batch/');
     }
     

3. Integration with Storage Disks

   • Use Laravel’s Storage facade alongside Fileman for disk-agnostic operations:

     $path = Fileman::upload($file, 's3://bucket/');
     Storage::disk('s3')->put($path, file_get_contents($file));
     

4. File Metadata Handling

   • Extract metadata (e.g., MIME type, size) before/after operations:

     $metadata = Fileman::getMetadata('path/to/file');
     

5. Event-Based Processing

   • Trigger events (e.g., file.uploaded) via Laravel’s Event system:

     event(new FileUploaded($path));
     

Integration Tips

• Middleware: Use middleware to enforce file size/type rules globally.
• Service Providers: Bind Fileman interfaces to custom implementations for testing.
• Artisan Commands: Create commands for bulk file operations (e.g., php artisan fileman:cleanup).

Gotchas and Tips

Pitfalls

1. Permission Issues

   • Ensure the storage directory has 755 permissions. Use chmod or Laravel’s Storage::makeDirectory().
   • For S3/FTP, verify credentials in .env or config/filesystems.php.

2. Path Handling

   • Avoid hardcoding paths; use storage_path(), public_path(), or Fileman::resolvePath().
   • Watch for trailing slashes in destinations (e.g., 'uploads/' vs 'uploads').

3. Overwriting Files

   • Default behavior may overwrite files. Use Fileman::uniqueName() to avoid collisions:

     $path = Fileman::upload($file, 'uploads/', ['unique' => true]);
     

4. Memory Limits

   • Large files may hit PHP’s memory_limit. Use chunked uploads or Storage::disk()->put() for streaming.

5. Testing

   • Mock Fileman in tests by binding a fake implementation in phpunit.xml or TestCase:

     $this->app->bind('Darvinstudio\Fileman\Contracts\Fileman', function() {
         return new FakeFileman();
     });
     

Debugging Tips

• Log File Operations

  • Enable Laravel’s debug mode (APP_DEBUG=true) and check logs for errors.
  • Add custom logging:

    \Log::debug('File uploaded to', ['path' => $path]);
    

• Verify Disk Configuration

  • Run php artisan storage:link if using symbolic links.
  • Test disk connectivity:

    php artisan storage:disk --list
    

Extension Points

1. Custom Drivers

   • Extend the package by creating a new disk driver (e.g., for Dropbox):

     Fileman::extend('dropbox', function() {
         return new DropboxDriver();
     });
     

2. Hooks/Events

   • Listen for file operations via Laravel’s events:

     Event::listen('fileman.uploaded', function($event) {
         // Post-upload logic (e.g., generate thumbnail)
     });
     

3. Configuration Overrides

   • Publish and modify the config:

     php artisan vendor:publish --tag=fileman-config
     

   • Override defaults in config/fileman.php.