本文详细讲解如何使用 Maatwebsite/Laravel-Excel 库从 PHP 数组导出数据到 Excel 文件。重点解决导出空文件这一常见问题，通过实现 `FromCollection` 和 `WithHeadings` 接口，并正确使用 `collection()` 方法将数组数据转换为 Laravel 集合，确保数据能够被正确识别并写入 Excel 文件，从而实现稳定、完整的数据导出功能。
在 Laravel 开发中，使用 Maatwebsite/Laravel-Excel 库进行数据导出是常见的需求。然而，开发者有时会遇到从 PHP 数组导出数据时生成空 Excel 文件的问题。这通常是由于未正确实现库所需的接口和方法导致的。本文将深入探讨如何正确配置和使用 Laravel-Excel 从数组导出数据，并解决空文件的问题。
1. 理解 Laravel-Excel 的数据源接口
Maatwebsite/Laravel-Excel 库通过一系列接口来定义不同的数据源和导出行为。对于从数组导出数据，最关键的两个接口是：
- FromCollection: 此接口要求你的导出类实现一个 collection() 方法，该方法必须返回一个 Laravel Collection 实例。这是库获取要导出数据的主要方式。
- WithHeadings: (可选但强烈推荐) 此接口要求你的导出类实现一个 headings() 方法，该方法返回一个字符串数组，用作 Excel 文件的第一行标题。
当导出类没有实现 FromCollection 接口或其 collection() 方法没有返回有效的 Collection 时，Laravel-Excel 将无法获取数据，从而导致生成一个空文件。
2. 构建正确的导出类
为了从数组正确导出数据，我们需要创建一个实现了 FromCollection 和 WithHeadings 接口的导出类。
假设我们有一个包含多个数据行的数组，每行又是一个包含多个字段的数组，例如：
使用 qbo-mileage CLI 及用户凭证，从 Airtable、Outlook 或 Google Calendar 记录生成 QuickBooks Online 里程 CSV 文件。
$dataToExport = [
['one', 'name'],
['two', 'family'],
['three', 'surname']
];以下是正确实现导出类的示例：
<?php
namespace App\Exports;
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithHeadings;
use Illuminate\Support\Collection; // 确保引入 Collection 类
class MyArrayExport implements FromCollection, WithHeadings
{
protected $data;
/**
* 构造函数，用于接收要导出的数据
*
* @param array $data 待导出的数组数据
*/
public function __construct(array $data)
{
$this->data = $data;
}
/**
* 返回一个 Laravel Collection 实例，包含所有要导出的数据
* 这是 FromCollection 接口要求实现的方法
*
* @return Collection
*/
public function collection(): Collection
{
// 将传入的数组数据转换为 Laravel Collection
// 确保每一行数据都是一个数组或对象
return collect($this->data);
}
/**
* 返回一个数组，定义 Excel 文件的列标题
* 这是 WithHeadings 接口要求实现的方法
*
* @return array
*/
public function headings(): array
{
// 根据你的数据结构定义合适的列标题
return [
'Identifier',
'Description',
];
}
}关键点解释：
- use Maatwebsite\Excel\Concerns\FromCollection; 和 use Maatwebsite\Excel\Concerns\WithHeadings;: 引入所需的接口。
- use Illuminate\Support\Collection;: 确保 collection() 方法返回的是正确的 Collection 类型。
- __construct(array $data): 构造函数用于接收外部传入的待导出数据。
- collection(): Collection: 这个方法是核心。它将 $this->data（即我们在构造函数中传入的原始数组）通过 collect() 辅助函数转换为一个 Laravel Collection 实例并返回。这是 Laravel-Excel 获取数据的正确途径。
- headings(): array: 这个方法定义了 Excel 文件的列头。它应该返回一个字符串数组，其顺序和内容与 collection() 方法返回的数据列相对应。
3. 触发 Excel 文件下载
一旦你创建了正确的导出类，就可以在控制器或路由中调用 Excel::download() 方法来触发文件下载。
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Maatwebsite\Excel\Facades\Excel;
use App\Exports\MyArrayExport; // 确保路径正确
class DataExportController extends Controller
{
/**
* 导出数据到 Excel 文件
*
* @return \Symfony\Component\HttpFoundation\BinaryFileResponse
*/
public function exportToArray()
{
$dataToExport = [
['one', 'name'],
['two', 'family'],
['three', 'surname']
];
// 创建 MyArrayExport 实例，并传入要导出的数据
// 然后调用 Excel::download 方法进行下载
return Excel::download(new MyArrayExport($dataToExport), 'exported_data.xlsx');
}
}你可以在 routes/web.php 中定义一个路由来访问这个方法：
use App\Http\Controllers\DataExportController;
Route::get('/export/array', [DataExportController::class, 'exportToArray']);现在，当你访问 /export/array 路由时，浏览器应该会下载一个名为 exported_data.xlsx 的 Excel 文件，其中包含你传入的数据和定义的标题。
4. 注意事项与最佳实践
- 安装 Maatwebsite/Laravel-Excel: 在使用之前，请确保你已经通过 Composer 安装了该库：composer require maatwebsite/excel，并完成了相应的配置（如发布配置文件）。
- 数据结构: FromCollection 接口期望你的 collection() 方法返回的 Collection 内部元素是数组或对象。如果你的数据是扁平的，例如 ['value1', 'value2']，它将被视为一行中的两个单元格。如果是 [['val1a', 'val1b'], ['val2a', 'val2b']]，则会被解析为两行两列。
- 内存管理: 对于非常大的数据集，直接将所有数据加载到内存中可能会导致内存溢出。在这种情况下，可以考虑使用 FromQuery 接口或 chunk 方法来分批处理数据。但对于中小型数组导出，FromCollection 是一个简单有效的选择。
- 错误处理: 在实际应用中，你可能需要添加错误处理逻辑，例如检查数据是否为空，或者在导出过程中捕获异常。
- 文件格式: Excel::download() 方法的第二个参数是文件名，其扩展名 (.xlsx, .csv, .xls) 会决定导出的文件格式。
总结
通过实现 FromCollection 和 WithHeadings 接口，并确保 collection() 方法返回一个有效的 Laravel Collection 实例，我们可以轻松地使用 Maatwebsite/Laravel-Excel 从 PHP 数组导出数据到 Excel 文件，并有效避免生成空文件的问题。理解这些核心接口和方法是成功进行 Laravel Excel 数据导出的关键。
