Exim Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require davask/exim
   

   Ensure your project uses Symfony 5.4+ or Laravel 8+ (via Symfony bridge) with SonataAdminBundle (if leveraging CMS features).

2. Configuration

   • Publish the package config:

     php artisan vendor:publish --provider="Davask\Exim\EximServiceProvider"
     

   • Update config/exim.php with your database/environment settings.
   • Register the bundle in config/bundles.php (Symfony) or ensure Laravel’s service provider is loaded.

3. First Use Case

   • Quick Data Export: Use the Exim\Exporter facade to export a model’s data to CSV/Excel:

     use Davask\Exim\Facades\Exporter;
     
     $data = Model::all()->toArray();
     Exporter::export($data, 'export.csv', 'text/csv');
     

   • CMS Integration: If using SonataAdmin, extend a CRUD controller to add export buttons:

     use Davask\Exim\Sonata\ExporterButton;
     
     class PostAdmin extends AbstractCRUDController {
         public function configureButtons() {
             $this->addButton(new ExporterButton());
         }
     }
     

Implementation Patterns

Core Workflows

1. Data Export

   • Model-to-File: Chain Exporter::export() with Eloquent collections:

     $users = User::with('roles')->get();
     Exporter::export($users, 'users.xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
     

   • Custom Mappers: Transform data before export using Exporter::map():

     Exporter::map($users, function ($user) {
         return [
             'name' => $user->name,
             'email' => strtolower($user->email),
             'role' => $user->roles->first()->name,
         ];
     });
     

2. Import Workflows

   • File-to-Database: Use Importer::import() with validation:

     $imported = Importer::import('file.csv', User::class, [
         'name' => 'Name',
         'email' => 'Email',
     ]);
     

   • Batch Processing: Handle large files with chunking:

     Importer::import('large_file.xlsx', User::class, [], 100); // 100 rows per chunk
     

3. SonataAdmin Integration

   • Dynamic Export Buttons: Add to any Sonata CRUD controller:

     $this->addButton(new ExporterButton('Export', 'export'), 'list', 'top');
     

   • Custom Export Actions: Extend ExporterButton to modify behavior:

     class CustomExporterButton extends ExporterButton {
         protected function getExportData() {
             return Model::query()->where('active', true)->get();
         }
     }
     

4. API Endpoints

   • Laravel Routes: Expose exports via API:

     Route::get('/export/users', function () {
         return Exporter::export(User::all(), 'users.json', 'application/json');
     });
     

   • Streaming Large Files: Use Symfony’s StreamedResponse for memory efficiency:

     return new StreamedResponse(function () {
         $handle = fopen('php://output', 'w');
         fputcsv($handle, ['name', 'email']);
         foreach (User::chunk(100) as $chunk) {
             foreach ($chunk as $user) {
                 fputcsv($handle, [$user->name, $user->email]);
             }
         }
         fclose($handle);
     }, 200, ['Content-Type' => 'text/csv']);
     

Gotchas and Tips

Pitfalls

1. Memory Limits

   • Issue: Large exports may hit PHP’s memory_limit.
   • Fix: Use chunking or streaming (e.g., Exporter::stream() if available).
   • Workaround: Increase memory_limit in php.ini temporarily or use set_time_limit().

2. SonataAdmin Compatibility

   • Issue: Button placement may break if SonataAdmin version mismatches.
   • Fix: Check sonata-project/admin-bundle version in composer.json (target ~3.50).
   • Debug: Clear cache after updates:

     php bin/console cache:clear
     

3. CSV/Excel Encoding

   • Issue: Special characters (e.g., é, ñ) may corrupt files.
   • Fix: Encode data explicitly:

     Exporter::export(array_map(function ($item) {
         return mb_convert_encoding($item, 'UTF-8');
     }, $data), 'export.csv');
     

4. Validation Errors

   • Issue: Imports may silently fail due to strict validation.
   • Fix: Enable debug mode or log errors:

     Importer::import('file.csv', User::class, [], [], true); // $debug = true
     

Debugging Tips

• Log Exports: Use Laravel’s logging to track export/import jobs:

  Exporter::export($data, 'log:export.log', 'text/plain'); // For debugging
  

• Check Config: Validate config/exim.php for correct database/queue settings.
• Test with Small Data: Start with 10–20 rows to verify mappings before scaling.

Extension Points

1. Custom Writers

   • Extend Davask\Exim\Writer\AbstractWriter to support new formats (e.g., PDF):

     class PdfWriter extends AbstractWriter {
         public function write(array $data, string $filename) {
             // Use Dompdf or similar
         }
     }
     

   • Register in config/exim.php:

     'writers' => [
         'pdf' => Davask\Exim\Writer\PdfWriter::class,
     ],
     

2. Pre/Post-Import Hooks

   • Bind events in EventServiceProvider:

     public function boot() {
         Event::listen(EximEvents::PRE_IMPORT, function ($event) {
             // Modify $event->data before import
         });
     }
     

3. Queue Exports

   • Dispatch exports as jobs for async processing:

     ExportJob::dispatch(User::all(), 'export.xlsx')->delay(now()->addMinute());
     

   • Implement ExportJob:

     class ExportJob implements ShouldQueue {
         use Dispatchable, InteractsWithQueue;
     
         public function handle() {
             Exporter::export($this->data, $this->filename);
         }
     }
     

Performance Quirks

• Database Locks: Imports on large tables may lock rows. Use transactions sparingly:

  DB::transaction(function () use ($data) {
      Importer::import('file.csv', Model::class, $mapping);
  });
  

• File Handling: Avoid writing to /tmp in production; use storage_path('app/exports') instead.