Update related AbstractElements and allow to clear caches after population

README.md

@@ -67,6 +67,30 @@ valantic_elastica_bridge:
         # 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
 ```
+## Events
+
+This project uses Symfony's event dispatcher. Here are the events that you can listen to:
+
+| Description                                         | Example Usage                                                        | Event Constant (`ElasticaBridgeEvents::`) | Event Object (`Model\Event\`)  |
+|-----------------------------------------------------|----------------------------------------------------------------------|-------------------------------------------|--------------------------------|
+| After an element has been refreshed in an index.    | Log Event, send notification                                         | `POST_REFRESH_ELEMENT_IN_INDEX`           | `RefreshedElementInIndexEvent` |
+| Before an element is refreshed in an index.         | Stop propagation of element in specific index                        | `PRE_REFRESH_ELEMENT_IN_INDEX`            | `RefreshedElementInIndexEvent` |
+| After an element has been refreshed in all indices. | Clear caches, refresh related Objects,  Log Event, send notification | `POST_REFRESH_ELEMENT`                    | `RefreshedElementEvent`        |
+| Before an element is refreshed in all indices.      | Stop propagation of element in all indices                           | `PRE_REFRESH_ELEMENT`                     | `RefreshedElementEvent`        |
+
+You 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.
+
+### Possible Use Cases for Events
+
+- clear cache after an element has been refreshed
+- send a notification after an element has been refreshed
+- log the event
+- update related elements in the index
+
+### Event Propagation
+
+When 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.
+You 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.
 
 ## Queue
 

phpstan-baseline.neon

@@ -1,10 +1,5 @@
 parameters:
 	ignoreErrors:
-		-
-			message: "#^Method Valantic\\\\ElasticaBridgeBundle\\\\EventListener\\\\Pimcore\\\\ChangeListener\\:\\:getFreshElement\\(\\) should return TElement of Pimcore\\\\Model\\\\Asset\\|Pimcore\\\\Model\\\\DataObject\\\\AbstractObject\\|Pimcore\\\\Model\\\\Document but returns Pimcore\\\\Model\\\\Asset\\|Pimcore\\\\Model\\\\DataObject\\\\AbstractObject\\|Pimcore\\\\Model\\\\Document\\.$#"
-			count: 1
-			path: src/EventListener/Pimcore/ChangeListener.php
-
 		-
 			message: "#^Call to function is_subclass_of\\(\\) with Pimcore\\\\Model\\\\Element\\\\AbstractElement and mixed will always evaluate to true\\.$#"
 			count: 1

src/Enum/ElementInIndexOperation.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Valantic\ElasticaBridgeBundle\Enum;
+
+enum ElementInIndexOperation
+{
+    case INSERT;
+    case UPDATE;
+    case DELETE;
+    case NOTHING;
+}

src/EventListener/Pimcore/ChangeListener.php

@@ -110,13 +110,15 @@ private function prepareHandle(AssetEvent|DataObjectEvent|DocumentEvent $event):
      */
     private function getFreshElement(AbstractElement $element): AbstractElement
     {
+        /** @var class-string<TElement> $elementClass */
         $elementClass = $element::class;
         $e = new PimcoreElementNotFoundException($element->getId(), $elementClass);
 
         if ($element->getId() === null) {
             throw $e;
         }
 
+        /** @var TElement */
         return $elementClass::getById($element->getId(), ['force' => true]) ?? throw $e;
     }
 

src/Messenger/Handler/RefreshElementHandler.php

@@ -23,6 +23,10 @@ public function __invoke(RefreshElement $message): void
     {
         $element = $this->resolveElement($message);
 
+        if ($message->isEventPropagationStopped()) {
+            PropagateChanges::stopPropagation();
+        }
+
         $this->propagateChanges->handle($element);
     }
 }

src/Messenger/Handler/RefreshElementInIndexHandler.php

@@ -28,6 +28,10 @@ public function __invoke(RefreshElementInIndex $message): void
         $index = $this->indexRepository->flattenedGet($message->index);
         $element = $this->resolveElement($message);
 
+        if ($message->isEventPropagationStopped()) {
+            PropagateChanges::stopPropagation();
+        }
+
         if ($index->usesBlueGreenIndices() && !$this->lockService->getIndexingLock($index)->acquire()) {
             $this->propagateChanges->handleIndex($element, $index, $index->getBlueGreenInactiveElasticaIndex());
         }

src/Messenger/Message/AbstractRefresh.php

@@ -11,10 +11,26 @@ abstract class AbstractRefresh
     /** @var class-string<ElementInterface> */
     public string $className;
     public int $id;
+    private bool $shouldStopEventPropagation = false;
+
+    public function isEventPropagationStopped(): bool
+    {
+        return $this->shouldStopEventPropagation;
+    }
+
+    public function stopEventPropagation(): void
+    {
+        $this->setShouldStopEventPropagation(true);
+    }
 
     protected function setElement(ElementInterface $element): void
     {
         $this->className = $element::class;
         $this->id = $element->getId() ?? throw new \InvalidArgumentException('Pimcore ID is null.');
     }
+
+    protected function setShouldStopEventPropagation(bool $stopEventPropagation): void
+    {
+        $this->shouldStopEventPropagation = $stopEventPropagation;
+    }
 }

src/Messenger/Message/RefreshElement.php

@@ -8,8 +8,11 @@
 
 class RefreshElement extends AbstractRefresh
 {
-    public function __construct(ElementInterface $element)
-    {
+    public function __construct(
+        ElementInterface $element,
+        bool $stopEventPropagation = false,
+    ) {
         $this->setElement($element);
+        $this->setShouldStopEventPropagation($stopEventPropagation);
     }
 }

src/Messenger/Message/RefreshElementInIndex.php

@@ -11,7 +11,9 @@ class RefreshElementInIndex extends AbstractRefresh
     public function __construct(
         ElementInterface $element,
         public readonly string $index,
+        bool $stopEventPropagation = false,
     ) {
+        $this->setShouldStopEventPropagation($stopEventPropagation);
         $this->setElement($element);
     }
 }

src/Model/Event/ElasticaBridgeEvents.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Valantic\ElasticaBridgeBundle\Model\Event;
+
+interface ElasticaBridgeEvents
+{
+    public const PRE_REFRESH_ELEMENT = 'valantic.elastica_bridge.pre_refreshed_element';
+    public const POST_REFRESH_ELEMENT = 'valantic.elastica_bridge.post_refreshed_element';
+    public const PRE_REFRESH_ELEMENT_IN_INDEX = 'valantic.elastica_bridge.pre_refreshed_element_in_index';
+    public const POST_REFRESH_ELEMENT_IN_INDEX = 'valantic.elastica_bridge.post_refreshed_element_in_index';
+}

src/Model/Event/RefreshedElementEvent.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Valantic\ElasticaBridgeBundle\Model\Event;
+
+use Pimcore\Model\Element\AbstractElement;
+use Symfony\Contracts\EventDispatcher\Event;
+use Valantic\ElasticaBridgeBundle\Index\IndexInterface;
+
+class RefreshedElementEvent extends Event
+{
+    /**
+     * @param array<IndexInterface> $indices
+     */
+    public function __construct(
+        private readonly AbstractElement $element,
+        private readonly array $indices,
+    ) {}
+
+    public function getElement(): AbstractElement
+    {
+        return $this->element;
+    }
+
+    /**
+     * @return array<IndexInterface>
+     */
+    public function getIndices(): array
+    {
+        return $this->indices;
+    }
+}

src/Model/Event/RefreshedElementInIndexEvent.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Valantic\ElasticaBridgeBundle\Model\Event;
+
+use Elastica\Index;
+use Pimcore\Model\Element\AbstractElement;
+use Symfony\Contracts\EventDispatcher\Event;
+use Valantic\ElasticaBridgeBundle\Enum\ElementInIndexOperation;
+use Valantic\ElasticaBridgeBundle\Index\IndexInterface;
+
+class RefreshedElementInIndexEvent extends Event
+{
+    public function __construct(
+        public readonly AbstractElement $element,
+        public readonly IndexInterface $index,
+        public readonly Index $elasticaIndex,
+        public readonly ElementInIndexOperation $operation,
+    ) {}
+
+    public function getElement(): AbstractElement
+    {
+        return $this->element;
+    }
+
+    public function getIndex(): IndexInterface
+    {
+        return $this->index;
+    }
+
+    public function getElasticaIndex(): Index
+    {
+        return $this->elasticaIndex;
+    }
+
+    public function getOperation(): ElementInIndexOperation
+    {
+        return $this->operation;
+    }
+}

src/Service/PropagateChanges.php

@@ -8,18 +8,26 @@
 use Elastica\Index;
 use Pimcore\Model\DataObject\AbstractObject;
 use Pimcore\Model\Element\AbstractElement;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\Messenger\MessageBusInterface;
 use Valantic\ElasticaBridgeBundle\Document\DocumentInterface;
+use Valantic\ElasticaBridgeBundle\Enum\ElementInIndexOperation;
 use Valantic\ElasticaBridgeBundle\Index\IndexInterface;
 use Valantic\ElasticaBridgeBundle\Messenger\Message\RefreshElementInIndex;
+use Valantic\ElasticaBridgeBundle\Model\Event\ElasticaBridgeEvents;
+use Valantic\ElasticaBridgeBundle\Model\Event\RefreshedElementEvent;
+use Valantic\ElasticaBridgeBundle\Model\Event\RefreshedElementInIndexEvent;
 use Valantic\ElasticaBridgeBundle\Repository\IndexRepository;
 
 class PropagateChanges
 {
+    private static bool $isPropagationStopped = false;
+
     public function __construct(
         private readonly IndexRepository $indexRepository,
         private readonly DocumentHelper $documentHelper,
         private readonly MessageBusInterface $messageBus,
+        private readonly EventDispatcherInterface $eventDispatcher,
     ) {}
 
     /**
@@ -32,8 +40,24 @@ public function handle(AbstractElement $element): void
     {
         $indices = $this->matchingIndicesForElement($this->indexRepository->flattenedAll(), $element);
 
+        $event = new RefreshedElementEvent($element, $indices);
+
+        if (!self::$isPropagationStopped) {
+            $this->eventDispatcher->dispatch($event, ElasticaBridgeEvents::PRE_REFRESH_ELEMENT);
+        }
+
         foreach ($indices as $index) {
-            $this->messageBus->dispatch(new RefreshElementInIndex($element, $index->getName()));
+            $this->messageBus->dispatch(
+                new RefreshElementInIndex(
+                    $element,
+                    $index->getName(),
+                    self::$isPropagationStopped || $event->isPropagationStopped()
+                )
+            );
+        }
+
+        if (!self::$isPropagationStopped && !$event->isPropagationStopped()) {
+            $this->eventDispatcher->dispatch($event, ElasticaBridgeEvents::POST_REFRESH_ELEMENT);
         }
     }
 
@@ -45,6 +69,11 @@ public function handleIndex(
         $this->doHandleIndex($element, $index, $elasticaIndex ?? $index->getElasticaIndex());
     }
 
+    public static function stopPropagation(): void
+    {
+        self::$isPropagationStopped = true;
+    }
+
     private function doHandleIndex(
         AbstractElement $element,
         IndexInterface $index,
@@ -69,19 +98,30 @@ private function doHandleIndex(
         }
 
         $isPresent = $this->isIdInIndex($document::getElasticsearchId($element), $elasticaIndex);
+        $shouldIndex = $document->shouldIndex($element);
 
-        if ($document->shouldIndex($element)) {
-            if ($isPresent) {
-                $this->updateElementInIndex($element, $elasticaIndex, $document);
-            }
+        $operation = match (true) {
+            !$isPresent && $shouldIndex => ElementInIndexOperation::INSERT,
+            $isPresent && $shouldIndex => ElementInIndexOperation::UPDATE,
+            $isPresent && !$shouldIndex => ElementInIndexOperation::DELETE,
+            default => ElementInIndexOperation::NOTHING,
+        };
 
-            if (!$isPresent) {
-                $this->addElementToIndex($element, $elasticaIndex, $document);
-            }
+        $event = new RefreshedElementInIndexEvent($element, $index, $elasticaIndex, $operation);
+
+        if (!self::$isPropagationStopped) {
+            $this->eventDispatcher->dispatch($event, ElasticaBridgeEvents::PRE_REFRESH_ELEMENT_IN_INDEX);
         }
 
-        if ($isPresent && !$document->shouldIndex($element)) {
-            $this->deleteElementFromIndex($element, $elasticaIndex, $document);
+        match ($operation) {
+            ElementInIndexOperation::INSERT => $this->addElementToIndex($element, $elasticaIndex, $document),
+            ElementInIndexOperation::UPDATE => $this->updateElementInIndex($element, $elasticaIndex, $document),
+            ElementInIndexOperation::DELETE => $this->deleteElementFromIndex($element, $elasticaIndex, $document),
+            ElementInIndexOperation::NOTHING => null,
+        };
+
+        if (!self::$isPropagationStopped && !$event->isPropagationStopped()) {
+            $this->eventDispatcher->dispatch($event, ElasticaBridgeEvents::POST_REFRESH_ELEMENT_IN_INDEX);
         }
 
         $this->documentHelper->resetTenantIfNeeded($document, $index);