How can you include column headers when exporting Eloquent to Excel in Laravel?
When using Laravel Excel to generate reports, it is common to encounter a dataset that renders correctly as rows of data but lacks descriptive column labels. In the scenario provided, the export executes without error, returning an .xlsx file where values like 1, 150, and dates appear directly under each other without identifying text such as "ID", "cost", or "created_at". This usually indicates that the package is not configured to automatically map model attributes to Excel headers.
By default, packages like Maatwebsite/Laravel-Excel do not assume a one-to-one mapping between database columns and Excel headers unless explicitly told so. When you implement FromQuery on your export class, the library scans the result set of your query. It expects an Exportable interface to define how that data should be transformed before being written to the sheet.
To fix this, you need to customize the mapping within your export class. The most direct approach is to implement the WithHeadings trait or manually define a mapping array in the map() method (if using older versions) or simply configure the sheet headers before adding the rows. Since you are implementing FromQuery, you should ensure that the query() method returns your Eloquent collection, but the critical logic happens in how you tell Laravel-Excel what to write.
In modern versions of Laravel Excel, if you rely on automatic header generation from the model, the library often struggles with mixed data types or specific column ordering unless you define them explicitly. You can override this by implementing the WithHeadings trait and defining a static array that maps your database columns to human-readable headers.
Here is how you can adjust your ProductExport class:
use Maatwebsite\Excel\Concerns\FromQuery;
use Maatwebsite\Excel\Concerns\WithHeadings;
class ProductExport implements FromQuery, WithHeadings
{
public function __construct(int $id)
{
$this->id = $id;
}
// Map your desired headers here
public static array $headings = [
'id' => 'ID',
'cost' => 'Cost',
'created_at' => 'Created At',
'updated_at' => 'Updated At',
// Add other columns as needed
];
public function query()
{
return ProductList::query()->where('id', $this->id);
}
}
By implementing WithHeadings and populating the $headings array, you instruct the exporter to write those specific strings as the first row of your spreadsheet. The keys in this array should correspond to the actual column names returned by your Eloquent query (or the attributes available on the model), while the values represent the text displayed in the Excel file.
If your ProductList model has accessors or mutators, ensure that the attribute names you reference in the $headings array match the keys of the resulting collection. If you are exporting raw columns from a table without a specific model accessor, you might need to use the actual column name as the key.
Another common pitfall involves using FromQuery when the underlying query returns a large dataset. The WithHeadings approach works well for standard queries, but if you find that headers are still missing despite this implementation, verify that your route is passing the request correctly and that no middleware or caching is interfering with the export class instantiation. Additionally, ensure that the ProductList::query()->where('id', $this->id) actually returns a collection of models that possess the attributes you are trying to display. If the query filters out necessary columns or joins incorrectly, the resulting rows will lack the data points required for your header mapping to function.
Finally, remember that this configuration is static within the class. If you need dynamic headers based on user permissions or different report types, consider creating separate export classes or using a factory pattern to instantiate the export with different heading configurations.
