PHP 8.1 不内置数据导入功能，需结合类库（如 maatwebsite/excel）、接口约束与新特性（交集类型、枚举）实现健壮导入；须用指定版本、路径传参、分块读取、编码处理及枚举统一状态与字段映射。
用 maatwebsite/excel 实现导入主流程
这是 Laravel 生态最主流方案，PHP 8.1 + Laravel 10/11 必须配对使用 maatwebsite/excel:^4.0 和 phpoffice/phpspreadsheet:^2.0。装错版本会直接报 Class not found 或 bindShared() 错误。
- 先清理旧包：
composer remove maatwebsite/excel - 再装指定版本：
composer require maatwebsite/excel:^4.0 phpoffice/phpspreadsheet:^2.0 - 导入时不能传
UploadedFile对象，必须是字符串路径：
✅ 正确：$path = $request->file('import')->store('imports'); Excel::import(new UsersImport, storage_path('app/' . $path));
❌ 错误：Excel::import(new UsersImport, $request->file('import'))
用交集类型约束导入处理器行为
PHP 8.1 的交集类型特别适合定义“既要能读取又要能写入”的导入处理器。比如一个类既要支持 Excel 行解析，又要能批量写入数据库：
- 定义两个接口：
CanReadRows和CanBulkInsert - 在服务方法中声明：
function handleImport(CanReadRows & CanBulkInsert $processor): void - 调用方传入的对象必须同时实现这两个接口，否则 PHP 在运行前就报错，避免漏掉关键能力
用 Enum 管理导入状态与字段映射
导入过程常涉及状态流转（如 Pending → Processing → Completed）和列名标准化（如 Excel 表头 "用户姓名" → 统一转为 "name"）。PHP 8.1 枚举天然适合：
- 定义
enum ImportStatus: string，带getDescription()方法返回中文说明 - 定义
enum ImportColumn: string，每个 case 映射 Excel 列与数据库字段：case NAME = 'user_name'; - 配合 match 表达式做列名归一化，避免 if-else 堆砌
防坑要点：乱码、空行、内存爆
真实业务中，用户上传的 Excel 常有中文乱码、空行、超大文件等问题。PHP 8.1 环境下要主动加处理：
立即学习“PHP免费学习笔记（深入）”；
- 读取时加
WithChunkReading：分块读，10 万行也不会内存溢出 - 加
WithSkippedEmptyRows：跳过全空行，防止解析失败 - 加
withEncoding('UTF-8')：Windows 下中文不再变???? - 表头统一转小写：
return array_change_key_case($row, CASE_LOWER);，避免'Name'和'name'不匹配 - 禁用 Laravel 缓存：
Cache::forget('import_config');，防止缓存导致Undefined array key 'type'
