Table Bundle Laravel Package

Getting Started

• Install the package with Composer and confirm the OpenSpout dependency resolves to v5:

  composer require <vendor>/<package>:^0.16
  composer show openspout/openspout
  

  Version 0.16.0 is a breaking release: exports no longer work with OpenSpout v4 or earlier. If your lockfile still has OpenSpout v4, run composer update openspout/openspout and re-run export tests before shipping.
• Look first at the package README’s export section, any publishable config file, and the package’s export class/interface. In day-to-day Laravel work, most usage will be: define an export, call it from a controller or queued job, and write the result to a configured filesystem disk.
• First use case: export a filtered Eloquent query to CSV or XLSX and store it on a disk.

  Route::get('/exports/orders', function () {
      return (new OrdersExport(Order::query()->latest()))->download('orders.xlsx');
  });
  

  Start with a small fixture (10–100 rows), verify the file opens, then move to queued exports for real data volumes.

Implementation Patterns

• One export class per domain concern. Keep headings, row mapping, and filtering inside the export class. Avoid putting column logic in controllers.
• Stream and chunk large exports. Use query builders with chunkById() or cursor() rather than get(). Pass filters as scalars or a small DTO, not as serialized Eloquent models.
• Queue anything user-facing. For large files, dispatch a job that writes to a private disk and notify the user when complete:

  ExportOrdersJob::dispatch($filters, $userId);
  

  Store the resulting path and expose a temporary signed URL rather than a public file.
• Use storage disks consistently. Configure a dedicated exports disk, set visibility and retention policies, and clean old files with a scheduled command.
• Separate CSV and XLSX paths where needed. CSV is best for large, simple data; XLSX is better for formatted output. Keep format-specific options in config rather than scattered through business logic.
• Wrap filters and column selection. A small value object such as OrderExportFilters makes queued exports easier to serialize, validate, and test.
• Test at the boundary. Use Storage::fake(), run the export, assert the file exists, and inspect row count or a few mapped values. Avoid asserting binary file contents.
• Integrate through events/notifications. Emit an application event when an export finishes so notifications, audit logs, and UI polling stay decoupled from the export class.

Gotchas and Tips

• OpenSpout v5 is mandatory in 0.16.0. Exports are not compatible with OpenSpout v4 and earlier. Check direct and transitive constraints, commit the updated lockfile, and verify CI uses the same resolved version. If you pass OpenSpout writer options directly, review the OpenSpout v5 upgrade notes—constructor signatures and option names may differ from v4.
• Do not mix OpenSpout majors. A transitive dependency still requiring v4 can produce confusing runtime errors or Composer conflicts. Use composer why openspout/openspout when in doubt.
• Memory spikes usually come from the query, not the writer. Streaming only helps if you avoid loading full collections and large relation graphs. Use with() carefully and select only needed columns.
• Queued exports must be serializable. Avoid closures, Eloquent models, or resource handles in job payloads. Pass IDs, arrays, and scalars.
• Excel and CSV edge cases: watch timezone/date formatting, numeric precision, UTF-8 BOM requirements for CSV, delimiter/encoding expectations, and formula injection. Prefix user-controlled cells beginning with =, +, -, or @ when exporting to spreadsheet formats.
• Filesystem behavior differs by disk. Local temp files, S3 multipart uploads, and permissions can fail differently. Test the actual production disk configuration, not only local.
• Debug with a tiny fixture first. If an export fails after upgrading, reduce to one row, check the resolved OpenSpout version, inspect the generated file, and confirm the package’s config is published and current.
• Extension points: keep custom writers, format handlers, and config overrides isolated behind package config or your own service classes. That makes future breaking upgrades—like this OpenSpout v5 requirement—much cheaper to absorb.