Merge pull request #1348 from formapro-forks/add-doctrine-queue-listner-doc

Add doctrine queue listener doc

Author: makasim

DependencyInjection/Configuration.php

@@ -537,6 +537,7 @@ protected function getPersistenceNode()
                 ->arrayNode('listener')
                     ->addDefaultsIfNotSet()
                     ->children()
+                        ->booleanNode('enabled')->defaultTrue()->end()
                         ->scalarNode('insert')->defaultTrue()->end()
                         ->scalarNode('update')->defaultTrue()->end()
                         ->scalarNode('delete')->defaultTrue()->end()

DependencyInjection/FOSElasticaExtension.php

@@ -334,7 +334,7 @@ private function loadTypePersistenceIntegration(array $typeConfig, ContainerBuil
         if (isset($typeConfig['finder'])) {
             $this->loadTypeFinder($typeConfig, $container, $elasticaToModelTransformerId, $typeRef, $indexName, $typeName);
         }
-        if (isset($typeConfig['listener'])) {
+        if (isset($typeConfig['listener']) && $typeConfig['listener']['enabled']) {
             $this->loadTypeListener($typeConfig, $container, $objectPersisterId, $indexName, $typeName);
         }
     }

Resources/doc/cookbook/doctrine-queue-listener.md

@@ -0,0 +1,64 @@
+# Doctrine queue listener
+
+FOSElasticaBundle subscribes on Doctrine events, such as insert, update, remove to adjust the index accordingly.
+The listener might start consuming more and more resources, most importantly time of http response.
+Or, Sometimes it fails, bringing the whole your app down too, because of ElasticSearch server is out of order or some bug in the code.
+Keep reading if you want to improve http response time or strive for better fault tolerance.
+
+Instead of doing everything in one single process the listener just sends a message to a worker (via [message queue](https://en.wikipedia.org/wiki/Message_queue)).
+The work does the actual synchronization job in background. 
+For queuing it uses [EnqueueBundle](https://github.com/php-enqueue/enqueue-dev/blob/master/docs/bundle/quick_tour.md) which supports a lot of MQ transports out of the box.
+
+## Installation
+
+I assume you already have `FOSElasticaBundle` installed, if not here's the [setup doc](../setup.md). 
+So, we only have to install `EnqueueElasticaBundle` and one of the MQ transports. 
+I am going to install the bundle and filesystem transport by way of example.
+
+```bash
+$ composer require enqueue/elastica-bundle:^0.8.1 enqueue/fs:^0.8
+```
+
+_**Note:** As long as you are on Symfony Flex you are done. If not, you have to do some extra things, like registering the bundle in your `AppKernel` class._  
+ 
+## Usage 
+
+The usage is simple, you have to disable the default listener:
+
+```yaml
+fos_elastica:
+    indexes:
+        acme_index:
+            types:
+                acme_type:
+                    persistence:
+                        driver: 'orm'
+                        model: 'AppBundle\Entity\Blog'
+                        listener: { enabled: false }
+```
+
+and enable the queue one:
+
+```
+enqueue_elastica:
+    doctrine:
+        queue_listeners:
+            -
+              index_name: 'acme_index'
+              type_name: 'acme_blog'
+              model_class: 'AppBundle\Entity\Blog'
+```
+
+Don't forget to run some queue consumers (the more you run the better performance you might get):
+
+```bash
+$ ./bin/console enqueue:consume --setup-broker -vvv 
+```
+
+or (use it only if you cannot use the solution above):
+
+```bash
+$ ./bin/console enqueue:transport:consume enqueue_elastica.doctrine.sync_index_with_object_change_processor -vvv 
+```
+
+[back to index](../index.md)

Resources/doc/cookbook/speed-up-populate-command.md

@@ -19,7 +19,7 @@ For queuing it uses [EnqueueBundle](https://github.com/php-enqueue/enqueue-dev/b
 ## Installation
 
 I assume you already have `FOSElasticaBundle` installed, if not here's the [setup doc](../setup.md). 
-So, we only have to install `EnqueueBundle` and one of the MQ transports. 
+So, we only have to install `EnqueueElasticaBundle` and one of the MQ transports. 
 I am going to install the bundle and filesystem transport by way of example.
 
 ```bash

Resources/doc/index.md

@@ -18,12 +18,15 @@ Cookbook Entries
 * [Custom Repositories](cookbook/custom-repositories.md)
 * [Pre Transform Event](cookbook/pre-transform-event.md)
 * [HTTP Headers for Elastica](cookbook/elastica-client-http-headers.md)
-* Performance - [Logging](cookbook/logging.md) - [Compression](cookbook/compression.md)
 * [Manual Providers](cookbook/manual-provider.md)
 * [Clustering - Multiple Connections](cookbook/multiple-connections.md)
 * [Suppressing server errors](cookbook/suppress-server-errors.md)
 * [Hints on result hydration](cookbook/hints-on-result-hydration.md)
 * [Multi type search](cookbook/multi-type-search.md)
 * [Attachments Handling](cookbook/attachments.md)
 * [Populate Events](cookbook/populate-events.md)
-* [Speed up populate command](cookbook/speed-up-populate-command.md)
+* Performance
+   - [Logging](cookbook/logging.md) 
+   - [Compression](cookbook/compression.md)
+   - [Speed up populate command](cookbook/speed-up-populate-command.md)
+   - [Doctrine queue listener](cookbook/doctrine-queue-listener.md)

Tests/DependencyInjection/FOSElasticaExtensionTest.php

@@ -4,6 +4,7 @@
 
 use Doctrine\ODM\MongoDB\DocumentManager;
 use FOS\ElasticaBundle\DependencyInjection\FOSElasticaExtension;
+use FOS\ElasticaBundle\Doctrine\Listener;
 use FOS\ElasticaBundle\Doctrine\RegisterListenersService;
 use FOS\ElasticaBundle\Doctrine\MongoDBPagerProvider;
 use FOS\ElasticaBundle\Doctrine\ORMPagerProvider;
@@ -521,4 +522,72 @@ public function testShouldRegisterPagerPersisterRegisterService()
         $this->assertSame(PagerPersisterRegistry::class, $listener->getClass());
         $this->assertSame([], $listener->getArgument(0));
     }
+
+    public function testShouldRegisterDoctrineORMListener()
+    {
+        $container = new ContainerBuilder();
+        $container->setParameter('kernel.debug', true);
+
+        $extension = new FOSElasticaExtension();
+        $extension->load([
+            'fos_elastica' => [
+                'clients' => [
+                    'default' => ['host' => 'a_host', 'port' => 'a_port'],
+                ],
+                'indexes' => [
+                    'acme_index' => [
+                        'types' => [
+                            'acme_type' => [
+                                'properties' => ['text' => null],
+                                'persistence' => [
+                                    'driver' => 'orm',
+                                    'model' => 'theModelClass',
+                                    'provider' => ['pager_provider' => true],
+                                    'listener' => null,
+                                    'finder' => null,
+                                ]
+                            ]
+                        ]
+                    ]
+                ]
+            ]
+        ], $container);
+
+        $this->assertTrue($container->hasDefinition('fos_elastica.listener.acme_index.acme_type'));
+    }
+
+    public function testShouldNotRegisterDoctrineORMListenerIfDisabled()
+    {
+        $container = new ContainerBuilder();
+        $container->setParameter('kernel.debug', true);
+
+        $extension = new FOSElasticaExtension();
+        $extension->load([
+            'fos_elastica' => [
+                'clients' => [
+                    'default' => ['host' => 'a_host', 'port' => 'a_port'],
+                ],
+                'indexes' => [
+                    'acme_index' => [
+                        'types' => [
+                            'acme_type' => [
+                                'properties' => ['text' => null],
+                                'persistence' => [
+                                    'driver' => 'orm',
+                                    'model' => 'theModelClass',
+                                    'provider' => ['pager_provider' => true],
+                                    'listener' => [
+                                        'enabled' => false,
+                                    ],
+                                    'finder' => null,
+                                ]
+                            ]
+                        ]
+                    ]
+                ]
+            ]
+        ], $container);
+
+        $this->assertFalse($container->hasDefinition('fos_elastica.listener.acme_index.acme_type'));
+    }
 }