{"id":19561837,"url":"https://github.com/valantic/pimcore-elastica-bridge","last_synced_at":"2025-04-27T00:31:24.278Z","repository":{"id":42002849,"uuid":"321982015","full_name":"valantic/pimcore-elastica-bridge","owner":"valantic","description":"Pimcore Elastica Bridge","archived":false,"fork":false,"pushed_at":"2025-04-11T15:42:50.000Z","size":2305,"stargazers_count":8,"open_issues_count":11,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-19T20:58:59.830Z","etag":null,"topics":["elastica","elasticsearch","pimcore"],"latest_commit_sha":null,"homepage":"https://valantic.github.io/pimcore-elastica-bridge/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valantic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-12-16T12:54:31.000Z","updated_at":"2025-04-04T18:16:19.000Z","dependencies_parsed_at":"2023-12-13T08:54:58.708Z","dependency_job_id":"c50ac7b5-737b-400a-a87d-fd97b00d8b38","html_url":"https://github.com/valantic/pimcore-elastica-bridge","commit_stats":{"total_commits":204,"total_committers":2,"mean_commits":102.0,"dds":0.004901960784313708,"last_synced_commit":"3c29ce256fd6793315f7d8566d86c8bfeee94ec2"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valantic%2Fpimcore-elastica-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valantic%2Fpimcore-elastica-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valantic%2Fpimcore-elastica-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valantic%2Fpimcore-elastica-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valantic","download_url":"https://codeload.github.com/valantic/pimcore-elastica-bridge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251072279,"owners_count":21532004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elastica","elasticsearch","pimcore"],"created_at":"2024-11-11T05:12:41.086Z","updated_at":"2025-04-27T00:31:23.890Z","avatar_url":"https://github.com/valantic.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elastica Bridge for Pimcore\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/valantic/pimcore-elastica-bridge.svg?style=flat-square)](https://packagist.org/packages/valantic/pimcore-elastica-bridge)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)\n[![PHP Checks](https://github.com/valantic/pimcore-elastica-bridge/actions/workflows/php.yml/badge.svg)](https://github.com/valantic/pimcore-elastica-bridge/actions/workflows/php.yml)\n\nThis package is developed by [valantic CEC Schweiz](https://www.valantic.com/en/services/digital-business/) and is under active development.\n\nThe only job of the bundle is to store Pimcore elements (assets, documents, data objects) into Elasticsearch documents.\n\n## Setup\n\n1. `composer require valantic/pimcore-elastica-bridge`\n1. Edit `config/bundles.php` and add `\\Valantic\\ElasticaBridgeBundle\\ValanticElasticaBridgeBundle::class =\u003e ['all' =\u003e true],`\n1. Configure the connection to your Elasticsearch cluster as seen in [`example/app/config/config.yaml`](example/app/config/config.yaml)\n1. Don't forget to register your newly created services (implementing `IndexInterface` etc.) in your `services.yaml`\n   ```yml\n   App\\Elasticsearch\\:\n   resource: '../../Elasticsearch'\n   ```\n1. Verify the setup by running `bin/console valantic:elastica-bridge:status`\n\n## Usage\n\nPlease see the [`docs/example/`](docs/example/) folder for a complete example. The following steps link to the corresponding section in the example and explain in a bit more detail what they are doing.\n\n### Define an index\n\n**The `IndexInterface` describes an index in Elasticsearch**, and contains methods that are required to create such an index. The easiest way to start is to `extend` the `AbstractIndex` class, which has most of the methods already implemented in a generic manner. In this case only two methods need to be implemented for a new index:\n\n- `getName` returns the name of the index. A suffix will be added for blue/green deployments, which are enabled by default.\n- `getAllowedDocuments` returns an array containing the FQCN of the documents that can be stored within this index. It is best to use the `::class` constant of the classes implementing the `DocumentInterface`.\n\nSee the [`ProductIndex` provided in the example](docs/example/src/Elasticsearch/Index/Product/ProductIndex.php) for a more detailed implementation containing additional queries and a tenant-aware functionality.\n\n### Define a document\n\n**A document describes a Pimcore element inside an index**, i.e. it represents an asset, document or data object managed in Pimcore inside the Elasticsearch index. A developer must tell this bundle about these elements by providing a class implementing the `DocumentInterface` . Most methods are already implemented in the `AbstractDocument`, so it is recommended to use that one as a base class. The four methods that need to be implemented are:\n\n- `getType` is either asset, document, data object, or variant and corresponds to an enum of `DocumentType`.\n- `getSubType` is very useful for data objects, since it allows to define what kind of data object this document is about. It is best to use the `::class` constant on the data object or the `Asset\\*` / `Document\\*` class.\n- `shouldIndex` should return a boolean indicating if the Pimcore element should be indexed or not.\n- `getNormalized` returns the associative array to be indexed. The `DataObjectNormalizerTrait` helps in this process with the following methods, all of which take the Pimcore element and an array describing the mapping:\n  - `plainAttributes` is for scalar attributes. Based on the mapping the document will contain the value in these properties.\n  - `localizedAttributes` is for localized Pimcore attributes. They will be stored in a `localized` field in the document with all languages as children.\n  - `relationAttributes` allow to store just a reference, i.e. the ID of a Pimcore element, instead of the entire object in the index.\n  - The mapping can either be an array defined without keys, in which case the Pimcore element's property will be indexed using the same name or a key-value pair if the property should be named differently in the index. **If a key-value pair is used, it is also possible to pass a function retrieving the Pimcore element and returning an arbitrary array.** This is very powerful and allows to implement almost any use case. Mind that it is also possible to mix both approaches, i.e. define some entries with a key and others without one.\n\nSee the [`ProductIndexDocument` provided in the example](docs/example/src/Elasticsearch/Index/Product/Document/ProductIndexDocument.php) for more details.\n\n## Configuration\n\n```yaml\nvalantic_elastica_bridge:\n    client:\n\n        # The DSN to connect to the Elasticsearch cluster.\n        dsn:                  'http://localhost:9200'\n\n        # If true, breadcrumbs are added to Sentry for every request made to Elasticsearch via Elastica.\n        should_add_sentry_breadcrumbs: false\n    indexing:\n\n        # To prevent overlapping indexing jobs. Set to a value higher than the slowest index. Value is specified in seconds.\n        lock_timeout:         300\n\n        # 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.\n        should_skip_failing_documents: false\n```\n## Events\n\nThis project uses Symfony's event dispatcher. Here are the events that you can listen to:\n\n| Description                                         | Example Usage                                                        | Event Constant (`ElasticaBridgeEvents::`) | Event Object (`Model\\Event\\`)  |\n|-----------------------------------------------------|----------------------------------------------------------------------|-------------------------------------------|--------------------------------|\n| After an element has been refreshed in an index.    | Log Event, send notification                                         | `POST_REFRESH_ELEMENT_IN_INDEX`           | `RefreshedElementInIndexEvent` |\n| Before an element is refreshed in an index.         | Stop propagation of element in specific index                        | `PRE_REFRESH_ELEMENT_IN_INDEX`            | `RefreshedElementInIndexEvent` |\n| After an element has been refreshed in all indices. | Clear caches, refresh related Objects,  Log Event, send notification | `POST_REFRESH_ELEMENT`                    | `RefreshedElementEvent`        |\n| Before an element is refreshed in all indices.      | Stop propagation of element in all indices                           | `PRE_REFRESH_ELEMENT`                     | `RefreshedElementEvent`        |\n\nYou can create an event subscriber or an event listener to listen to these events. Please refer to the [Symfony documentation](https://symfony.com/doc/current/event_dispatcher.html) for more information on how to use the event dispatcher.\n\n### Possible Use Cases for Events\n\n- clear cache after an element has been refreshed\n- send a notification after an element has been refreshed\n- log the event\n- update related elements in the index\n\n### Event Propagation\n\nWhen refreshing multiple elements, each refresh triggers an event that could potentially lead to another refresh, resulting in an endless loop. To prevent this, you can disable event propagation during the refresh process.\nYou can disable event propagation by setting `$stopPropagateEvents` to `true` in the `RefreshElement` Message constructor or by calling `stopEventPropagation()` on the message before you add it to the queue.\n\n## Queue\n\n[Set up a worker](https://symfony.com/doc/current/messenger.html#consuming-messages-running-the-worker) to process `elastica_bridge_index`. Alternatively you can route the transport to use the `sync` handler: `framework.messenger.transports.elastica_bridge_index: 'sync'`.\n\n## Indexing\n\n### Bulk\n\n```\n$ console valantic:elastica-bridge:index --help\nDescription:\n  Ensures all the indices are present and populated.\n\nUsage:\n  valantic:elastica-bridge:index [options] [--] [\u003cindex\u003e...]\n\nArguments:\n  index                          Optional: indices to process. Defaults to all if empty\n\nOptions:\n  -d, --delete                   Delete i.e. re-create existing indices\n  -p, --populate                 Populate indices\n  -c, --check                    Perform post-populate checks\n  -h, --help                     Display this help message\n```\n\n### Specific\n\nThe bridge automatically listens to Pimcore events and updates documents as needed. If needed, call `\\Valantic\\ElasticaBridgeBundle\\Service\\PropagateChanges::handle` or execute `console valantic:elastica-bridge:refresh`.\n\nThis can be globally disabled by calling `\\Valantic\\ElasticaBridgeBundle\\EventListener\\Pimcore\\ChangeListener::disableListener();`.\n\nYou can also dispatch a `Valantic\\ElasticaBridgeBundle\\Messenger\\Message\\RefreshElement` message to handle updates to related objects which are not triggered by the `ChangeListener`.\n\n## Status\n\n```\n$ console valantic:elastica-bridge:status --help\nDescription:\n  Displays the status of the configured Elasticsearch indices\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalantic%2Fpimcore-elastica-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalantic%2Fpimcore-elastica-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalantic%2Fpimcore-elastica-bridge/lists"}