README

Doctrine 全文搜索引擎

在 Doctrine 实体中实现一个易于使用的搜索引擎。

对于基本使用，您只需定义一个搜索实体及其属性的映射，搜索引擎将确保它们被正确加载，并自动根据找到的候选结果对搜索结果进行排序。

想法

该软件包的目的是提供一个简单的 API，用于 Doctrine 实体的高级全文搜索。在请求开始时，构建一个搜索方案，并确保根据相关性自动找到并返回最佳结果。

📦 安装 & 基本用法

要手动安装该软件包，请调用 Composer 并执行以下命令

$ composer require baraja-core/doctrine-fulltext-search

然后，在 NEON 配置中注册 DoctrineFulltextSearchExtension

extensions:
    doctrineFulltextSearch: Baraja\Search\DoctrineFulltextSearchExtension

或者您也可以手动创建 \Baraja\Search\Search 的实例。

搜索通过构建查询（映射实体和列）进行

$results = $this->search->search($query, [
    Article::class => [':title'],
    User::class => ':username', // it can also be an ordinary string for a single column
    UserLogin::class => [':ip', 'hostname', 'userAgent'],
]);

echo $results; // Uses the default HTML renderer

或者您可以使用 SelectorBuilder，具有完整严格的类型验证和提示方法来构建查询

$results = $this->search->selectorBuilder($query)
    ->addEntity(Article::class)
        ->addColumnTitle('title')
    ->addEntity(User::class)
        ->addColumnTitle('username')
    ->addEntity(UserLogin::class)
        ->addColumnTitle('ip')
        ->addColumn('hostname')
        ->addColumnSearchOnly('userAgent')
    ->search();

echo $results;

无需转义输出，所有逻辑都由引擎自动解决。

🛠️ 开关和特殊字符

:username - 该列将用作标题

!slug - 该列将用于搜索，但在 perex 输出中被忽略。

_durationTime - 该列将加载到实体中，但在计算相关性时不会被考虑，也不会包含在 perex 中。

content.versions.haystack - 实体之间的关系自动创建连接并加载最后一个属性。

versions(content) - 自定义获取器（自动连接 versions 列，但调用 getContent() 获取数据）。

⚙️ 标题设置

如果我们使用列名开头的冒号（例如 ':username'），它将自动用作标题。

即使标题不包含搜索词，标题也会显示。

标题可能为空，也可能不存在（可能是 null）。

如果标题不存在，则引擎可以自动根据找到的文本中的最佳出现位置计算它。

查询规范化

搜索查询将自动规范化，并移除没有搜索意义的 停用词。

可以通过实现 IQueryNormalizer 接口并在 DIC 容器中重写它来在特定项目中覆盖该算法。

🗺️ 浏览搜索结果

search() 方法的输出是 SearchResult 类型的实体，该实体实现了 \Iterator 接口，以便可以轻松遍历结果。

🚩 提示：如果您只需要快速打印搜索结果，并且外观要求不高，则 SearchResult 实体直接实现了 __toString() 方法，可以直接将结果渲染为 HTML。

搜索结果总结了所有实体中所有搜索的结果。所有结果都通过 getItems() 方法获得 - 输出将是一个 SearchItem[] 类型的实体数组。

然而，我们通常需要批量编译查询，然后分别列出，例如类别和产品。为此，请使用辅助方法 getItemsOfType(string $type)，该方法仅根据传入的参数返回类型为 SearchItem[] 的结果数组的子集。

渲染特定的搜索结果

我们使用 getItems() 或 getItemsOfType() 方法获取我们遍历的搜索结果。但是如何处理特定的结果呢？

重要的是要注意，在此点我们不再有 __toString() 方法可用，必须我们自己渲染结果（理想情况下在模板中）。

对于大多数情况，现成的辅助程序就足够了

• getTitle() 返回找到的实体的标题，作为字符串或 null。
• getTitleHighlighted() 在内部调用 getTitle()，如果结果是有效的字符串，则用 <i class="highlight"> 和 </i> 为每个单词着色。
• getSnippet() 返回找到的实体的摘要，总结原始实体中最佳找到的区域（例如，包含搜索词的文章摘要）。可以返回更多摘要（单独的出现由冒号分隔）。始终返回字符串（可以为空）。
• getTitleHighlighted() 在内部调用 getSnippet() 并用 <i class="highlight"> 和 </i> 为每个单词着色。
• getScore() 返回结果的相对（根据每个项目的搜索查询和可用数据，上下文不同）评分（根据此参数自动排序结果）。
• getEntity() 返回 Doctrine 内部生成的原始找到的实体。搜索使用 PARTIAL 选择执行，因此并非所有属性始终都可用。
• entityToArray() 返回自身作为数组。字符串会自动规范化。

分页

获取结果的方法（getItems() 和 getItemsOfType()）都接受参数 $limit（默认 10）和 $offset（默认 0）。

分页最好使用 Nette Pagination 实现。

通过 SearchResult 实体的上方方法 getCountResults() 获取结果总数。

读取找到的实体

搜索引擎使用 PARTIAL 加载数据库实体，并将结果实体包装到搜索结果中，因此您可以随时通过在特定搜索结果上方调用 ->getEntity() 来加载它们。

✅ 您是否想查询？

如果没有找到结果，或者它们的数量“很小”（该定义由算法根据特定项目的分析自行确定），则可能（可能不）提供有关最佳搜索查询纠正的建议。

为获取帮助，请通过 SearchResult 上方的 getDidYouMean() 方法。输出是字符串（更好的搜索查询）或 null。

最佳搜索查询纠正是由搜索引擎根据每个项目内部使用 机器学习 方法的高级搜索分析自行获得的。每次搜索都会自动保存有关搜索查询、结果数量和其他信号的统计数据，并在必要时进行回顾性分析。

获取帮助是自然的，并且不容易受到影响。搜索引擎力求最大限度地客观，并提供用户搜索的其他词语，并尽可能根据当前上下文返回尽可能多的相关结果。内部使用复杂的数学函数，我们根据所有项目的经验不断改进。

📊 搜索结果评分系统

在搜索过程中，首先会编制一个搜索结果的候选列表。然后，这些结果将分别通过一个评估算法，该算法在范围 0 - 512 内进行自动的“相对”评估（基于各种信号，如搜索查询、最近用户历史、语言、物理位置、实体内容和类型）（结果始终为 int）。

根据点评分，结果会自动排序。

可以通过实现 IScoreCalculator 接口并在 DIC 容器中重写它来覆盖评分算法。

📄 许可证

baraja-core/doctrine-fulltext-search 采用 MIT 许可证。有关更多详细信息，请参阅 LICENSE 文件。