Download the PHP package businessg/laravel-excel without Composer

businessg/laravel-excel

Laravel 框架的 Excel 同步/异步导入导出组件，提供开箱即用的 HTTP 接口自动注册、CLI 命令、进度追踪、消息推送、数据库日志。

Hyperf 版本请查看 businessg/hyperf-excel

目录

• 1. 快速开始
• 2. 配置参考
  • 2.1 excel.php — 组件核心配置
  • 2.1.1 事件监听器（listeners）
  • 2.2 excel_business.php — 业务配置
• 3. API 接口参考
• 4. 实现一个「导出」完整流程
• 5. 实现一个「导入」完整流程
• 6. 异步导入导出与队列配置
• 7. 配置类字段与样式参考
  • 7.1 ExportConfig — 导出配置类
  • 7.2 导出 Sheet
  • 7.3 导出 Column
  • 7.4 Style — 单元格样式
  • 7.5 SheetStyle — Sheet 级样式
  • 7.6 ImportConfig — 导入配置类
  • 7.7 导入 Sheet
  • 7.8 导入 Column
• 8. 内置 Demo 配置
• 9. 依赖组件与配置
• 错误状态码

1. 快速开始

1.1 环境要求

1.2 PHP 扩展

验证扩展已安装：

1.3 安装

包已配置 Laravel Package Auto-Discovery，ExcelServiceProvider 自动注册，无需手动添加。

1.4 发布配置文件

生成：

• config/excel.php — 组件核心配置
• config/excel_business.php — 业务导入导出配置

1.5 数据库迁移

启用数据库日志（dbLog.enabled = true）时执行：

创建 excel_log 表。建表 SQL 如下（也可手动执行）：

2. 配置参考

2.1 excel.php — 组件核心配置

2.1.1 事件监听器（listeners）

组件启动时会把"内置默认监听器 + listeners 追加配置"合并后注册到 Laravel Event。

内置默认监听器（始终启用，无需在 listeners 中重复声明）：

listeners 语义——追加，不是覆盖：

• 不配置或 []：仅注册默认监听器
• 配置类名数组：在默认之后按顺序追加注册
• 重复类名：自动去重（按首次出现位置保留）

最小示例（启用过程日志监听）：

编写自定义监听器：

继承 BusinessG\BaseExcel\Listener\AbstractBaseListener，通过 listen() 返回关注的事件类名数组，process() 统一路由到同名方法（支持的事件见 BusinessG\BaseExcel\Event\*）。

2.2 excel_business.php — 业务配置

此文件注册所有业务的导入导出配置，key 即为 business_id。

导出配置项说明

导入配置项说明

3. API 接口参考

启用 http.enabled = true 后自动注册。路径格式为 {prefix}/excel/{action}。

以 prefix = 'api' 为例。

3.1 导出 — {prefix}/excel/export

请求参数：

响应（异步或同步+UPLOAD）：

response 在异步模式下为 null，需通过 progress 接口获取最终文件路径。 同步 + OUT 模式时直接返回文件流（浏览器下载），无 JSON 响应。

3.2 导入 — {prefix}/excel/import

请求参数：

响应：

3.3 进度查询 — {prefix}/excel/progress

请求参数： token（必填）

响应：

status 状态码：

3.4 消息查询 — {prefix}/excel/message

请求参数： token（必填）

响应：

消息为消费式，取后即删。isEnd = true 时表示全部消息已输出完毕，可停止轮询。 当 fieldNaming = 'snake' 时，字段名为 is_end。

3.5 导入信息 — {prefix}/excel/info

请求参数： business_id（必填）

响应：

当 fieldNaming = 'snake' 时，字段名为 template_url。

3.6 文件上传 — {prefix}/excel/upload

请求参数： file（必填，.xlsx/.xls）

响应：

4. 实现一个「导出」完整流程

以"订单导出"为例。

第 1 步：启用 HTTP 路由

编辑 config/excel.php：

第 2 步：创建导出配置类

新建 app/Excel/OrderExportConfig.php：

第 3 步：注册到业务配置

编辑 config/excel_business.php：

第 4 步：调用

通过 API 调用：

通过命令行调用：

5. 实现一个「导入」完整流程

以"订单导入"为例，包含动态导入模板的完整配置。

第 1 步：创建导入模板导出配置

动态模板是一个特殊的导出配置：同步 + 直接输出（OUT），浏览器访问即下载模板文件。

新建 app/Excel/OrderImportTemplateConfig.php：

第 2 步：创建导入配置类

新建 app/Excel/OrderImportConfig.php：

第 3 步：注册到业务配置

编辑 config/excel_business.php：

第 4 步：调用

API 完整流程：

命令行调用：

6. 异步导入导出与队列配置

6.1 配置队列连接

确保 config/queue.php 中有可用连接（推荐 redis）：

6.2 绑定组件到队列

编辑 config/excel.php：

6.3 配置类中声明异步

注意：异步模式下 outPutType 必须为 UPLOAD，因为 OUT（直接输出）需要同步 HTTP 响应。

6.4 启动 Queue Worker

6.5 异步调用流程

7. 配置类字段与样式参考

所有配置类均通过数组构造（new Class(['key' => 'value'])），属性名即数组 key。

7.1 ExportConfig — 导出配置类

继承 ExportConfig 并覆盖属性或实现 getSheets() 方法。

outPutType 常量：

约束：isAsync = true 时 outPutType 必须为 upload（异步无法直接输出流）。

必须实现的方法：

7.2 导出 Sheet

每个 Sheet 对应 Excel 中的一个工作表。

data 回调参数 ExportCallbackParam：

7.3 导出 Column

每个 Column 定义一列的表头标题、数据字段映射、宽度和样式。

多行表头示例（说明行 + 列标题行）：

7.4 Style — 单元格样式

Style 可应用于 Column 的 style（数据行）或 headerStyle（表头行）。

常用常量：

样式综合示例：

7.5 SheetStyle — Sheet 级样式

7.6 ImportConfig — 导入配置类

继承 ImportConfig 并实现 getSheets() 方法。

7.7 导入 Sheet

callback 参数 ImportRowCallbackParam：

7.8 导入 Column

8. 内置 Demo 配置

组件预置以下 Demo 配置，发布配置后即可直接使用，便于快速验证：

快速验证： 只需 http.enabled = true，即可测试：

9. 依赖组件与配置

以下 Composer 包由组件自动引入，无需手动安装。但部分包需要确认已配置：

9.1 Filesystem

导出文件默认存储到 local 磁盘。确认 config/filesystems.php 中配置：

如需存储到 OSS/S3 等云存储，安装对应 Flysystem 适配器并修改 excel.php 的 drivers.xlswriter.disk。

9.2 Redis

确认 config/database.php 中 Redis 配置可连接：

9.3 Queue — 异步模式需要

使用异步导入导出时，确认队列连接：

错误状态码

组件使用统一的五位数错误状态码（ExcelErrorCode 常量类），0 表示成功。

License

MIT