使用Maatwebsite Laravel Excel导入xlsx时无法创建模型对象

问题描述 #

使用Maatwebsite Laravel Excel导入带表头的XLSX文件时，抛出SQL错误：

SQLSTATE[23000]: Integrity constraint violation: 1048 Column 'confirmation_number' cannot be null

CSV文件可正常导入，仅XLSX出现该问题，且dd($row)能看到文件中的数据。

排查与解决步骤 #

1. 检查XLSX表头匹配度 #

XLSX文件的表头可能存在大小写差异、前后空格或不可见字符，导致Laravel Excel无法正确映射到$row['confirmation_number']：

• 打开XLSX文件，确认表头内容为confirmation_number（无空格、无大小写变化）；
• 若表头是带空格的格式（如Confirmation Number），Laravel Excel默认会自动转换为蛇形命名confirmation_number，但需确保无额外空格；
• 可将表头复制到纯文本编辑器（如Notepad++），检查是否有隐藏字符。

2. 过滤空行/无效行 #

XLSX文件可能包含空行或无效行，导致某行的confirmation_number为空。在LetterImport的model方法中添加过滤逻辑：

public function model(array $row)
{
    // 过滤confirmation_number为空的行
    if (empty(trim($row['confirmation_number'] ?? ''))) {
        return null;
    }

    return new Confirmation([
        'confirmation_number' => $row['confirmation_number'],
        'guest_name'          => $row['guest_name'],
        'guest_address'       => $row['guest_address'],
        'email'               => $row['email'],
        'checkin'             => $row['checkin'],
        'checkout'            => $row['checkout']
    ]);
}

3. 验证表头行设置 #

确认headingRow()返回的行号与XLSX实际表头行一致：

• 若XLSX的表头在第2行（第1行是文档标题），需修改headingRow()返回2：

public function headingRow(): int
{
    return 2; // 对应实际表头所在行
}

4. 调试所有导入行 #

临时将ToModel改为ToArray，查看所有导入行的键值对，确认是否存在confirmation_number为空的行：

// 修改LetterImport.php
namespace App\Imports;

use Maatwebsite\Excel\Concerns\ToArray;
use Maatwebsite\Excel\Concerns\WithHeadingRow;

class LetterImport implements ToArray, WithHeadingRow
{
    public function array(array $rows)
    {
        dd($rows); // 输出所有行数据，检查每一行的confirmation_number字段
    }

    public function headingRow(): int
    {
        return 1;
    }
}

运行导入后，查看输出的$rows数组，确认是否存在异常行。

5. 检查单元格格式 #

XLSX中confirmation_number列的单元格可能存在格式问题：

• 确保单元格格式为“文本”或“常规”，避免因格式转换导致值为空；
• 检查单元格是否有隐藏的空格或换行符，可通过trim()处理值：

'confirmation_number' => trim($row['confirmation_number']),

内容的提问来源于stack exchange，提问作者sikios182