README

此包由 valantic CEC Schweiz 开发，并处于积极开发中。

此包的唯一任务是存储 Pimcore 元素（资产、文档、数据对象）到 Elasticsearch 文档。

配置

1. composer require valantic/pimcore-elastica-bridge
2. 编辑 config/bundles.php 并添加 \Valantic\ElasticaBridgeBundle\ValanticElasticaBridgeBundle::class => ['all' => true],
3. 根据 example/app/config/config.yaml 中的示例配置您的 Elasticsearch 集群连接
4. 别忘了在您的 services.yaml 中注册新创建的服务（实现 IndexInterface 等）

   App\Elasticsearch\:
   resource: '../../Elasticsearch'

5. 通过运行 bin/console valantic:elastica-bridge:status 验证配置

用法

请参阅 docs/example/ 文件夹中的完整示例。以下步骤链接到示例中的相应部分，并更详细地解释了它们所做的工作。

定义索引

IndexInterface 描述了 Elasticsearch 中的索引，并包含创建此类索引所需的方法。最简单的方法是扩展 AbstractIndex 类，该类已以通用方式实现了大多数方法。在这种情况下，只需实现两个新索引所需的方法

• getName 返回索引的名称。对于默认启用的蓝绿部署，将添加一个后缀。
• getAllowedDocuments 返回一个数组，包含可以存储在此索引中的文档的完全限定类名。最好使用实现 DocumentInterface 的类的 ::class 常量。

请参阅示例中提供的 ProductIndex，以获取包含更多查询和租户感知功能的更详细实现。

定义文档

文档描述了索引内的 Pimcore 元素，即它表示在 Elasticsearch 索引中管理的资产、文档或数据对象。开发人员必须通过提供实现 DocumentInterface 的类来告诉此包关于这些元素。大多数方法已在 AbstractDocument 中实现，因此建议将其用作基类。需要实现以下四个方法

• getType 是资产、文档、数据对象或变体，对应于 DocumentType 的枚举。
• getSubType 对于数据对象非常有用，因为它允许定义此类文档是关于什么类型的数据对象。最好使用数据对象或 Asset\* / Document\* 类的 ::class 常量。
• shouldIndex 应返回一个布尔值，指示 Pimcore 元素是否应被索引。
• getNormalized 返回要索引的关联数组。以下方法帮助在此过程中，所有这些方法都接受 Pimcore 元素和描述映射的数组
  • plainAttributes 用于标量属性。根据映射，文档将包含这些属性中的值。
  • localizedAttributes 用于本地化 Pimcore 属性。它们将在文档的 localized 字段中存储，作为所有语言的子节点。
  • relationAttributes 允许仅存储引用，即 Pimcore 元素的 ID，而不是在索引中存储整个对象。
  • 映射可以是未定义键的数组，在这种情况下，Pimcore 元素的属性将使用相同的名称索引，或者如果属性在索引中应使用不同的名称，则可以使用键值对。如果使用键值对，还可以传递一个函数来检索 Pimcore 元素并返回任意数组。这非常强大，可以实施几乎任何用例。请注意，也可以混合这两种方法，即定义一些具有键的条目，而其他则没有。

有关更多详细信息，请参阅ProductIndexDocument 示例。

配置

valantic_elastica_bridge:
    client:

        # The DSN to connect to the Elasticsearch cluster.
        dsn:                  'https://:9200'

        # If true, breadcrumbs are added to Sentry for every request made to Elasticsearch via Elastica.
        should_add_sentry_breadcrumbs: false
    indexing:

        # To prevent overlapping indexing jobs. Set to a value higher than the slowest index. Value is specified in seconds.
        lock_timeout:         300

        # If true, when a document fails to be indexed, it will be skipped and indexing continue with the next document. If false, indexing that index will be aborted.
        should_skip_failing_documents: false

事件

此项目使用 Symfony 的事件调度器。以下是可以监听的事件：

您可以创建事件订阅者或事件监听器来监听这些事件。有关如何使用事件调度器的更多信息，请参阅Symfony 文档。

事件的潜在用例

• 在元素刷新后清除缓存
• 在元素刷新后发送通知
• 记录事件
• 更新索引中的相关元素

事件传播

在刷新多个元素时，每个刷新都会触发一个事件，这可能导致另一个刷新，从而产生无限循环。为了避免这种情况，可以在刷新过程中禁用事件传播。您可以通过在 RefreshElement 消息构造函数中将 $stopPropagateEvents 设置为 true 或在将消息添加到队列之前调用 stopEventPropagation() 来禁用事件传播。

队列

设置一个工作进程来处理 elastica_bridge_index。或者，您可以路由传输以使用 sync 处理器：framework.messenger.transports.elastica_bridge_index: 'sync'。

索引

批量

$ console valantic:elastica-bridge:index --help
Description:
  Ensures all the indices are present and populated.

Usage:
  valantic:elastica-bridge:index [options] [--] [<index>...]

Arguments:
  index                          Optional: indices to process. Defaults to all if empty

Options:
  -d, --delete                   Delete i.e. re-create existing indices
  -p, --populate                 Populate indices
  -c, --check                    Perform post-populate checks
  -h, --help                     Display this help message

特定

桥接器会自动监听 Pimcore 事件并根据需要更新文档。如果需要，可以调用 \Valantic\ElasticaBridgeBundle\Service\PropagateChanges::handle 或执行 console valantic:elastica-bridge:refresh。

这可以通过调用 \Valantic\ElasticaBridgeBundle\EventListener\Pimcore\ChangeListener::disableListener(); 全局禁用。

您还可以分发一个 Valantic\ElasticaBridgeBundle\Messenger\Message\RefreshElement 消息来处理由 ChangeListener 触发的外部对象的更新。

状态

$ console valantic:elastica-bridge:status --help
Description:
  Displays the status of the configured Elasticsearch indices