Voyager Excel Laravel Package

Getting Started

tu6ge/voyager-excel is a Voyager-focused Excel/CSV import/export helper. v2.2.0 adds custom export format support, making it more useful when built-in XLSX/CSV output is not enough.

Start here:

1. Install with Composer and confirm the package supports your Laravel/Voyager versions:

   composer require tu6ge/voyager-excel
   

2. Publish/configure package assets if the package exposes config:

   php artisan vendor:publish --provider="Tu6ge\VoyagerExcel\VoyagerExcelServiceProvider"
   

3. Review the package README and config for the export action, route, and formatter/export-class registration point.
4. First use case: export one simple Voyager BREAD table to CSV/XLSX, then add a custom format for a domain-specific output such as fixed-width text, XML, or accounting CSV.

Treat v2.2.0 as an additive minor release. The release note shows a new capability, not an obvious breaking change, but pin the version if custom format registration depends on the new extension point.

Implementation Patterns

• Standard BREAD export first. Wire the package into a Voyager BREAD action or admin route and verify a basic export before customizing formats. This confirms permissions, field mapping, and response handling.
• Custom format as a dedicated class. For v2.2.0, create a small formatter/exporter class that accepts the BREAD query or rows and returns a streamed response. Keep it separate from Voyager controllers so it can be tested directly.
• Register formats centrally. Use the package’s config or service-provider extension point to map a format alias to your class. Avoid scattering format logic across BREAD definitions.
• Reuse the BREAD field map. Let the package resolve Voyager field types, then apply your custom formatting on top. This keeps exports consistent with the admin UI.
• Queue large exports. For big tables, generate files in a queued job and expose a signed download route. Do not rely on synchronous exports for production-scale data.
• Gate access explicitly. Wrap export routes in Voyager admin/auth middleware and, where needed, a policy check for the BREAD table.
• Version the custom format contract. If downstream systems consume the format, include a format version in the filename or header and add regression tests.

Example workflow:

1. Export a sample BREAD table with the built-in CSV writer.
2. Add a custom format class for the target system.
3. Register it in config as, for example, accounting_csv.
4. Add a test asserting headers, delimiter, encoding, and empty-dataset behavior.
5. Roll out behind an admin-only route and monitor memory/time for large exports.

Gotchas and Tips

• Clear config cache after registering formats. Laravel config caching can hide a newly added custom format. Run php artisan config:clear during debugging.
• Watch memory for large exports. Custom formatters can accidentally load the entire result set. Prefer chunking/streaming and test with realistic row counts.
• Handle Voyager field types explicitly. Relationships, JSON columns, media/file fields, and timestamps often need normalization before output. Do not assume the package renders every BREAD field exactly as the admin UI does.
• Check encoding and escaping. Custom CSV/XML/fixed-width formats need correct BOM, delimiter, quote, and XML-escaping behavior. Add tests for commas, quotes, newlines, and non-ASCII text.
• Confirm compatibility. Voyager is legacy in many Laravel versions; verify PHP, Laravel, and maatwebsite/excel constraints before upgrading. v2.2.0’s custom format feature should be treated as requiring that version or later.
• Debug at the formatter boundary. Log the resolved BREAD query, row count, selected format alias, and response headers. Most failures are registration, permission, or field-mapping issues rather than export-library bugs.
• Extension points to prefer: custom exporter/formatter class, config-driven format alias, and a package event or callback if available. Avoid overriding vendor controllers unless the package has no stable extension point.
• Add empty and failure tests. Exporting zero rows, invalid BREAD slugs, and unauthorized requests should return predictable responses rather than broken files.