Support Laravel Package

Getting Started

1. Installation:

   composer require derafu/support
   

   Verify PHP 8.5+ compliance via:

   php -v
   

2. First Use Case: Use Derafu\Support\Facades\Zip for memory-efficient ZIP creation:

   use Derafu\Support\Facades\Zip;
   
   Zip::create('export.zip')
       ->addFile(public_path('file1.txt'))
       ->addDirectory(storage_path('logs'))
       ->save();
   

3. Where to Look First:

   • Facade Methods: Zip, Csv, Mime, Collection (see Derafu Docs).
   • Laravel Integration: Check config/derafu.php (if auto-generated) for package settings.
   • Test Coverage: Run php artisan test --filter=Derafu to validate core utilities.

Implementation Patterns

1. Facade-Driven Workflows

Pattern: Replace manual instantiation with facades for cleaner code:

// Before (manual)
$zip = new \Derafu\Support\ZipStream();
$zip->addFile(...);

// After (facade)
Zip::create('archive.zip')->addFile(...);

Integration Tip:

• Bind facades in AppServiceProvider:

  public function boot()
  {
      \Derafu\Support\Facades\Zip::setStoragePath(storage_path('exports'));
  }
  

2. CSV Processing Pipeline

Workflow:

// Parse CSV from API response
$csv = Csv::fromString($apiResponse)
    ->setDelimiter(';')
    ->toCollection();

// Export to database
User::insert($csv->toArray());

Tip: Chain with Laravel’s Queue for async processing:

dispatch(new ProcessCsvJob($csvData));

3. Mime Type Handling

Use Case: Dynamic file responses in controllers:

public function download()
{
    $path = storage_path('file.pdf');
    $mime = Mime::fromPath($path);

    return response()->file($path)
        ->header('Content-Type', $mime);
}

Tip: Cache MIME types in config/derafu.php for performance:

'mime' => [
    'cache' => true,
    'ttl' => 3600,
],

4. Collection Augmentation

Pattern: Extend Laravel collections with Derafu methods:

$users = collect($users)
    ->groupByKey('department.id') // Derafu method
    ->mapToGroups(fn($user) => ['name' => $user->name]);

Tip: Override Laravel’s Collection alias in config/app.php:

'aliases' => [
    'Collection' => Derafu\Support\Facades\Collection::class,
],

5. File System Abstraction

Integration:

• Combine with Laravel’s Storage facade:

  use Derafu\Support\Facades\File;
  
  $zip = Zip::create('backup.zip');
  Storage::disk('s3')->files()->each(fn($file) => $zip->addFile($file));
  $zip->save();
  

Gotchas and Tips

Pitfalls

1. Facade Registration:

   • Gotcha: Facades won’t auto-register if DerafuServiceProvider isn’t loaded.
   • Fix: Manually register in config/app.php:

     'providers' => [
         Derafu\Support\DerafuServiceProvider::class,
     ],
     

2. ZipStream Memory Leaks:

   • Gotcha: Large files may exhaust memory if not streamed.
   • Tip: Use Zip::stream() for server responses:

     return Zip::stream('large.zip')
         ->addFile($largeFile)
         ->toResponse('archive.zip');
     

3. CSV Encoding Issues:

   • Gotcha: League CSV defaults to UTF-8; may corrupt non-UTF files.
   • Fix: Explicitly set encoding:

     Csv::fromFile('data.csv', 'ISO-8859-1');
     

4. Carbon Facade Conflict:

   • Gotcha: Overriding Laravel’s Carbon facade breaks now() helpers.
   • Tip: Use Derafu\Support\Facades\Carbon only in specific contexts.

Debugging Tips

• Zip Errors: Enable debug mode in config/derafu.php:

  'zip' => [
      'debug' => env('APP_DEBUG', false),
  ],
  

• Collection Methods: Use dd($collection->getDebugDump()) to inspect internals.
• CSV Validation: Test with php-cs-fixer to catch encoding issues early.

Extension Points

1. Custom Zip Handlers:

   Zip::extend('custom', function($zip) {
       $zip->addPassword('secret');
       return $zip;
   });
   

2. Mime Type Overrides:

   Mime::override(['txt' => 'text/plain-custom']);
   

3. Collection Macros:

   Collection::macro('snakeKeys', function() {
       return $this->mapWithKeys(fn($item) => [
           Str::snake(key($item)) => $item,
       ]);
   });
   

Performance Quirks

• Zip Compression: Disable compression for speed:

  Zip::create('fast.zip')->setCompression(false);
  

• CSV Streaming: Use Csv::stream() for >10MB files to avoid timeouts.
• Mime Caching: Clear cache after MIME type updates:

  php artisan derafu:clear-mime-cache
  

Laravel-Specific Workarounds

1. Service Provider Integration:

   public function register()
   {
       $this->app->singleton('derafu.zip', fn() => new \Derafu\Support\ZipStream());
   }
   

2. Command Bus Integration:

   use Derafu\Support\Facades\Zip;
   
   class ExportCommand implements ShouldQueue
   {
       public function handle()
       {
           Zip::create('export.zip')->addFiles(...)->save();
       }
   }
   

3. Event Listeners:

   public function handle(FileExported $event)
   {
       Zip::create('archive.zip')->addFile($event->path)->save();
   }