Laravel Scout集成MeiliSearch：含空格ID的搜索问题求解

问题背景 #

PostgreSQL数据库与外部源同步，所有ID包含空格，但MeiliSearch不支持id字段包含空格。尝试修改toSearchableArray()后导入提示成功，但索引无数据；使用属性转换能完成导入，却引发应用内其他问题且search()方法失效——原因是MeiliSearch返回的ID为替换下划线后的格式，与数据库原ID不匹配，导致Scout无法找到对应实体。

当前Scout配置：

'index-settings' => [
    MyModelName::class => [
        'filterableAttributes' => ['id', 'name'],
        'sortableAttributes' => ['created_at'],
    ]
],

尝试过的toSearchableArray()写法：

public function toSearchableArray()
{
    $array = $this->toArray();
    // Replace whitespaces with underscores in the 'id' field
    $data['id'] = trim(str_replace(' ', '_', $array['id']));
    $data['name'] = trim($array['name']);
    return $data;
}

尝试过的属性转换写法：

protected function id(): Attribute
{
    return Attribute::make(
        get: fn (string $value) => trim(str_replace(' ', '_', $value)),
    );
}

可行解决方案 #

方案1：自定义MeiliSearch主键字段，保留原ID用于匹配 #

MeiliSearch支持指定自定义主键，无需强制使用id。我们可以将处理后的无空格字段设为主键，同时保留原ID作为普通字段存入索引，既满足MeiliSearch格式要求，又能在搜索后匹配数据库记录。

1. 修改模型的toSearchableArray()，添加处理后的主键字段并保留原ID：

public function toSearchableArray()
{
    $array = $this->toArray();
    return [
        'search_id' => trim(str_replace(' ', '_', $array['id'])),
        'id' => $array['id'], // 保留原ID用于后续数据库匹配
        'name' => trim($array['name']),
        'created_at' => $this->created_at,
    ];
}

2. 更新Scout配置，指定自定义主键并调整索引设置：

'index-settings' => [
    MyModelName::class => [
        'primaryKey' => 'search_id', // 指定自定义主键
        'filterableAttributes' => ['search_id', 'id', 'name'],
        'sortableAttributes' => ['created_at'],
    ]
],

3. 重新导入数据：

php artisan scout:import "App\Models\MyModelName"

4. 重写模型的resolveScoutModelsByIds()方法，实现ID格式转换匹配：

public function resolveScoutModelsByIds($ids)
{
    // 将MeiliSearch返回的search_id转换回原ID格式
    $originalIds = array_map(function($searchId) {
        return str_replace('_', ' ', $searchId);
    }, $ids);
    
    return $this->whereIn('id', $originalIds)->get();
}

方案2：自定义Scout的文档ID生成逻辑（不修改模型属性） #

Laravel Scout允许通过getScoutKey()和getScoutKeyName()方法自定义文档ID，无需修改模型的id属性或toSearchableArray()，避免影响应用内其他逻辑。

1. 在模型中重写这两个方法：

// 生成符合MeiliSearch要求的文档ID（替换空格为下划线）
public function getScoutKey()
{
    return trim(str_replace(' ', '_', $this->id));
}

// 指定Scout使用的键名（保持MeiliSearch的文档ID字段名为'id'）
public function getScoutKeyName()
{
    return 'id';
}

2. 调整toSearchableArray()，确保原ID存入索引：

public function toSearchableArray()
{
    $array = $this->toArray();
    $array['name'] = trim($array['name']);
    return $array;
}

3. 保持原有Scout索引设置不变，重新导入数据后，重写resolveScoutModelsByIds()完成ID转换：

public function resolveScoutModelsByIds($ids)
{
    $originalIds = array_map(function($scoutId) {
        return str_replace('_', ' ', $scoutId);
    }, $ids);
    
    return $this->whereIn('id', $originalIds)->get();
}

原toSearchableArray()失效原因 #

Laravel Scout默认使用模型的getScoutKey()生成文档ID，而非toSearchableArray()中的id字段。因此即使你在toSearchableArray()中修改了id，Scout仍会传递带空格的原模型ID给MeiliSearch，导致MeiliSearch拒绝存储，最终索引无数据。

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