Laravel Nova Excel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require maatwebsite/laravel-nova-excel
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Maatwebsite\Excel\Nova\NovaExcelServiceProvider"
   

2. First Use Case: Extend a Nova Resource to enable Excel exports:

   use Maatwebsite\Excel\Nova\Exports\ExcelExport;
   
   class UserResource extends Resource
   {
       public function fields(Request $request)
       {
           return [
               // Your fields...
           ];
       }
   
       public function export()
       {
           return ExcelExport::make('users.xlsx', function () {
               return User::query();
           });
       }
   }
   

3. Where to Look First:

   • Official Nova Excel Documentation
   • config/nova-excel.php for configuration options.
   • app/Exports directory (auto-generated by the package) for custom export classes.

Implementation Patterns

Core Workflows

1. Basic Exports: Use ExcelExport to generate simple exports directly from Nova Resources:

   public function export()
   {
       return ExcelExport::make('users.xlsx', function () {
           return User::with('roles')->get();
       });
   }
   

2. Custom Exports: Create dedicated export classes in app/Exports:

   namespace App\Exports;
   
   use Maatwebsite\Excel\Concerns\FromQuery;
   use App\Models\User;
   
   class UserExport implements FromQuery
   {
       public function query()
       {
           return User::query()->where('active', true);
       }
   }
   

   Then reference in Resource:

   public function export()
   {
       return ExcelExport::make('active_users.xlsx', new UserExport());
   }
   

3. Dynamic Filters: Pass request filters to exports:

   public function export()
   {
       return ExcelExport::make('filtered_users.xlsx', function () {
           return User::where('name', 'like', '%' . $this->request->input('search') . '%');
       });
   }
   

4. Batch Actions: Export selected records from Nova’s batch actions:

   public function actions(Request $request)
   {
       return [
           ExportSelected::make('Export Selected', new UserExport($request->input('resources'))),
       ];
   }
   

Integration Tips

• Nova Tool Integration: Add a custom tool to Nova’s sidebar for quick access:

  public function tools()
  {
      return [
          new ExcelExportTool(),
      ];
  }
  

• Event Listeners: Trigger exports on model events (e.g., created):

  User::created(function ($user) {
      ExcelExport::queue(new UserExport(), 'user_export_' . $user->id . '.xlsx');
  });
  

• Queueing Exports: Offload heavy exports to queues:

  public function export()
  {
      return ExcelExport::queue(new UserExport(), 'users.xlsx');
  }
  

Gotchas and Tips

Common Pitfalls

1. Memory Limits:

   • Large exports may hit PHP’s memory limit. Use chunking:

     public function query()
     {
         return User::query()->cursor(); // Stream records instead of loading all at once
     }
     

   • Configure chunk_size in config/nova-excel.php.

2. Relationship Loading:

   • Eager-load relationships to avoid N+1 queries:

     return User::with('roles', 'posts')->get();
     

   • Use loadMissing() for dynamic relationships.

3. CSV vs. XLSX:

   • CSV exports may truncate data. Prefer XLSX for complex data:

     ExcelExport::make('users.xlsx', ...)->withFormat('xlsx');
     

4. Timezone Issues:

   • Ensure dates use UTC or a consistent timezone:

     Excel::create('users.xlsx', function ($excel) {
         $excel->setTimezone('UTC');
     });
     

Debugging Tips

• Log Exports: Enable logging in config/nova-excel.php:

  'log' => [
      'enabled' => true,
      'path' => storage_path('logs/nova-excel.log'),
  ],
  

• Test Locally: Use php artisan nova:serve to test exports before deploying.

• Check Disk Space: Large exports may fill disk space. Monitor storage/framework/excel or queue storage.

Extension Points

1. Custom Headers/Footers: Use WithHeadings and WithCustomStartCell:

   use Maatwebsite\Excel\Concerns\WithHeadings;
   
   class UserExport implements WithHeadings
   {
       public function headings(): array
       {
           return ['ID', 'Name', 'Email'];
       }
   }
   

2. Styling: Apply styles via WithStyles:

   use Maatwebsite\Excel\Concerns\WithStyles;
   use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
   
   class UserExport implements WithStyles
   {
       public function style(Worksheet $sheet)
       {
           $sheet->getStyle('A1')->applyFromArray([
               'font' => ['bold' => true],
           ]);
       }
   }
   

3. Conditional Logic: Use WithMapping for dynamic cell values:

   use Maatwebsite\Excel\Concerns\WithMapping;
   
   class UserExport implements WithMapping
   {
       public function map($user): array
       {
           return [
               'status' => $user->active ? 'Active' : 'Inactive',
           ];
       }
   }
   

4. Multi-Sheet Exports: Combine multiple exports into one file:

   ExcelExport::make('combined.xlsx', function () {
       return [
           new UserExport(),
           new PostExport(),
       ];
   })->withSheets([
       'users' => new UserExport(),
       'posts' => new PostExport(),
   ]);
   

Configuration Quirks

• Default Disk: Set the default disk for exports in config/nova-excel.php:

  'disk' => 'public',
  

• Filename Sanitization: Use sanitizeFilename() to avoid invalid characters:

  ExcelExport::make(sanitizeFilename('user export.xlsx'), ...);
  

• Nova Version Compatibility: Ensure compatibility with your Nova version (check release notes).