Improve documentation

README.md

@@ -11,9 +11,11 @@ http://www.elasticsearch.org/guide/reference/setup/installation.html
 #### Download
 
 With submodule:
+
     git submodule add git://github.com/ruflin/Elastica vendor/elastica
 
 With clone:
+
     git clone git://github.com/ruflin/Elastica vendor/elastica
 
 #### Register autoloading
@@ -83,6 +85,8 @@ Most of the time, you will need only one.
 
 Here we created a "website" index, that uses our "default" client.
 
+Our index is now available as a service: `foq_elastica.index.website`
+
 #### Declare a type
 
 Elasticsearch type is comparable to doctrine entity repository.
@@ -101,14 +105,19 @@ Elasticsearch type is comparable to doctrine entity repository.
                             lastName: { boost: 3 }
                             aboutMe: 
 
+Our type is now available as a service: `foq_elastica.index.website.user`
+
 ### Populate the types
 
     php app/console foq:elastica:populate
 
+This command deletes recreates the declared indexes and types.
+It applies the configured mappings to the types.
+
 This command needs providers to insert new documents in the elasticsearch types.
 There are 2 ways to create providers.
 If your elasticsearch type matches a doctrine repository, go for the doctrine automatic provider.
-Or, for complete flexibility, go for explicit provider.
+Or, for complete flexibility, go for manual provider.
 
 #### Doctrine automatic provider
 
@@ -134,7 +143,7 @@ Two drivers are actually supported: orm and mongodb.
 
 ##### Use a custom doctrine query builder
 
-You can control which entitie will be indexed by specifying a custom query builder method.
+You can control which entities will be indexed by specifying a custom query builder method.
 
                     doctrine:
                         driver: orm
@@ -143,4 +152,114 @@ You can control which entitie will be indexed by specifying a custom query build
                             query_builder_method: createIsActiveQueryBuilder
 
 Your repository must implement this method and return a doctrine query builder.
-                            
+
+##### Change the batch size
+
+By default, ElasticaBundle will index documents by paquets of 100.
+You can change this value in the provider configuration.
+
+                    doctrine:
+                        driver: orm
+                        model: Application\UserBundle\Entity\User
+                        provider:
+                            batch_size: 100
+
+##### Change the document identifier field
+
+By default, ElasticaBundle will use the `id` field of your entities as the elasticsearch document identifier.
+You can change this value in the provider configuration.
+
+                    doctrine:
+                        driver: orm
+                        model: Application\UserBundle\Entity\User
+                        provider:
+                            identifier: id
+
+#### Manual provider
+
+Create a service with the tag "foq_elastica.provider".
+
+        <service id="acme.search_provider.user" class="Acme\UserBundle\Search\UserProvider">
+            <tag name="foq_elastica.provider" />
+            <argument type="service" id="foq_elastica.index.website.user" />
+        </service>
+
+Its class must implement `FOQ\ElasticaBundle\Provider\ProviderInterface`.
+
+        <?php
+
+        namespace Acme\UserBundle\Provider;
+
+        use FOQ\ElasticaBundle\Provider\ProviderInterface;
+        use Elastica_Type;
+
+        class UserProvider implements ProviderInterface
+        {
+            protected $userType;
+
+            public function __construct(Elastica_Type $userType)
+            {
+                $this->userType = $userType;
+            }
+
+            /**
+             * Insert the repository objects in the type index
+             *
+             * @param Closure $loggerClosure
+             */
+            public function populate(Closure $loggerClosure)
+            {
+                $loggerClosure('Indexing users');
+
+                $this->userType->addDocuments(array(
+                    array('username' => 'Bob')
+                ));
+            }
+        }
+
+You will find a more complete implementation example in src/FOQ/ElasticaBundle/Provider/DoctrineProvider.php
+
+### Search
+
+You can just use the index and type Elastica objects, provided as services, to perform searches.
+
+    /** var Elastica_Type */
+    $userType = $this->container->get('foq_elastica.index.website.user');
+
+    /** var Elastica_ResultSet */
+    $resultSet = $userType->search('bob');
+
+#### Doctrine finder
+
+If your elasticsearch type is bound to a doctrine entity repository,
+you can get your entities instead of Elastica results when you perform a search.
+Declare that you want a doctrine finder in your configuration:
+
+    foq_elastica:
+        clients:
+            default: { host: localhost, port: 9200 }
+        indexes:
+            website:
+                client: default
+                types:
+                    user:
+                        mappings:
+                            # your mappings
+                    doctrine:
+                        driver: orm
+                        model: Application\UserBundle\Entity\User
+                        provider:
+                        finder:
+
+You can now use the `foq_elastica.finder.website.user` service:
+
+    /** var FOQ\ElasticaBundle\Finder\MappedFinder */
+    $userFinder = $container->get('foq_elastica.finder.website.user');
+
+    /** var array of Acme\UserBundle\Entity\User */
+    $users = $finder->find('bob');
+
+You can even get paginated results!
+
+    /** var Zend\Paginator\Paginator */
+    $userPaginator = $finder->findPaginated('bob');