Updated Documentation for v5.x (#762)

* updated the changelog

* updated the mapping docs

* added docs on routing annotation:

* updated crud chapter

* updated search documentation

* updated the scan documentation

* updated the upgrade documentation

* updated docs for results parsing

* updated overwriting section

Author: einorler

CHANGELOG.md

@@ -5,24 +5,31 @@
 - Array iterator now returns document _id field as well.
 - Document annotation now has an options support.
 You can pass any settings along parameters you want. Simply just put them in the options.
+- `Manager::getSettings()` was added. Returns the currently configured settings for manager index.
+- `Manager::getAliases()` was added. Gets Elasticsearch aliases information.
 - Added `text` and `keyword` property types support.
+- Added `murmur3`, `attachments`, `percolator` property type support
+- Added `hash_map` annotation. #747
+- Added `ONGR\ElasticsearchBundle\Exception` namespace.
 - Added `char_filter` analysis support.
 - All features and fixes from 1.2.x
 - Added `document_dir`. From now on you can change documents directory for each mapped bundle.
 - No more needed to define analysis in manager, it will be collected automatically from documents.
 
 ### Breaking changes
 - Removed all deprecations from 1.x version.
+- Removed `_ttl` metafield annotation.
 - Service name `@annotations.cached_reader` changed to `@es.annotations.cached_reader` #717
 - From Document annotation removed all properties except `type`. From now on everything has to be defined in the `options`.
-- `string` property type was deprecated in elasticsearch 5.0, please use text or keyword accordingly.
+- `string` property type was deprecated in elasticsearch 5.0, please use `text` or `keyword` accordingly.
  More info: https://www.elastic.co/blog/strings-are-dead-long-live-strings
 - `auth` in the configuration was removed. Use authentication information directly in host or create event listener
  to modify client creation. There are too many ways to authenticate elasticsearch. That said we leaving this customisation to the user due difficult support. 
 - `connections` node in configuration was removed. Use `index` from now on. There was absolute
  misunderstanding to have exposed connections, we never saw any benefits to use single connection
  between several managers.  
-- `analysis` node in `index`/`connection` was deprecated. From now on used analyzers, filters and other
+- Changed the namespace of the `DocumentParserException` to `ONGR\ElasticsearchBundle\Mapping\Exception`. #722
+- `analysis` node in `index`/`connection` was deprecated. From now on used analyzers, filters, etc. must be provided in document annotations
 - `Results` (constants container for result type definitions) class was removed in favor for
  new find functions with predefined types in the names.
 - Export service now uses own query calling instead of elasticsearch-php. It was changes due a bug

Resources/doc/crud.md

@@ -24,7 +24,7 @@ class Content
     public $id;
 
     /**
-     * @ES\Property(type="string")
+     * @ES\Property(type="keyword")
      */
     public $title;
 }
@@ -44,7 +44,9 @@ $manager = $this->get('es.manager');
 
 ## Repositories
 
-In addition manager provides repository access, which enables direct access to the elasticsearch type.  Repositories represents a document. Whenever you need to do any action with a repository to get it:
+In addition manager provides repository access, which enables direct access to the elasticsearch type.  
+Repository represents a document. Whenever you need to do any action with a repository, you can access 
+it like this:
 
 ```php
 
@@ -53,7 +55,7 @@ $repo = $manager->getRepository('AppBundle:Content');
 
 ```
 
-So instead you can call just:
+Alternatively:
 
 ```php
 

Resources/doc/mapping.md

@@ -178,14 +178,14 @@ class Product
 }
 ```
 
-> There is no mandatory to have private properties, and public will work as well.
- We are firmly recommend using private according to OOP best practices.  
+> It is not mandatory to have private properties, and public will work as well.
+ However, we firmly recommend using private according to OOP best practices.  
 
 #### Document annotation configuration
 
 - `@ES\Document(type="product")` Annotation defines that this class will represent elasticsearch type with name `content`.
-- You can append any options from elasticsearch type options in `options` variable.
- E.g. you want to add `enable:false` so it will look like: `@ES\Document(type="product", options={"enable":"false"})`
+- You can append any valid elasticsearch type options to the `options` variable.
+ E.g. if you want to add `enable:false` it will look like this: `@ES\Document(type="product", options={"enable":"false"})`
 - `type` parameter is for type name. This parameter is optional, if there will be no parameter set,
 ElasticsearchBundle will create a type with lower cased class name.
 
@@ -194,13 +194,13 @@ ElasticsearchBundle will create a type with lower cased class name.
 
 For defining type properties, there is a `@ES\Property` annotation. The only required
 attribute is `type` - Elasticsearch field type to specify what kind of information
-will be indexed. By default, the field name generated from property name by converting
-it to "snake case" string. You can specify the custom name by setting `name` attribute.
+will be indexed. By default, the field name is generated from property name by converting
+it to "snake case" string. You can specify a custom name by setting the `name` attribute.
 
 > Read more about elasticsearch supported types [in the official documentation][2].
 
 To add a custom setting for the property like analyzer include it in the `options` variable.
-Analyzers names defined in `config.yml` `analysis` [read more in the topic above](#Mapping configuration).
+Analyzers names must be defined in `config.yml` under the `analysis` node (read more in the topic above).
 Here's an example how to add it:
 
 ```php
@@ -289,7 +289,7 @@ class CategoryObject
 
 ```
 
-> Class name can be anything, we called it `CategoryObject` to make it more readable and notice that is an object.
+> Class name can be anything, we called it `CategoryObject` to make it more readable. Notice that it is an object, not a document.
 
 For this particular example the mapping in elasticsearch will look like this:
 
@@ -317,7 +317,7 @@ For this particular example the mapping in elasticsearch will look like this:
 
 To insert a document with mapping from example above you have to create 2 objects:
 
- ```php
+```php
  
   $category = new CategoryObject();
   $category->setTitle('Jeans');
@@ -330,11 +330,11 @@ To insert a document with mapping from example above you have to create 2 object
   $manager->persist($product);
   $manager->commit();
  
- ```
+```
 
 ##### Multiple objects
 
-As shown in the example above, by ElasticsearchBundle default only a single object will be saved in the document.
+As shown in the example above, by ElasticsearchBundle default, only a single object will be saved in the document.
 Meanwhile, Elasticsearch database doesn't care if in an object is stored as a single value or as an array. 
 If it is necessary to store multiple objects (array), you have to add `multiple=true` to the annotation. While
 initiating a document with multiple items you need to initialize property with the new instance of `Collection()`.
@@ -347,6 +347,7 @@ Here's an example:
 namespace AppBundle\Document;
 
 use ONGR\ElasticsearchBundle\Annotation as ES;
+use ONGR\ElasticsearchBundle\Collection\Collection;
 
 /**
  * @ES\Document()
@@ -396,7 +397,6 @@ And the object:
 namespace AppBundle\Document;
 
 use ONGR\ElasticsearchBundle\Annotation as ES;
-use ONGR\ElasticsearchBundle\Collection\Collection;
 
 /**
  * @ES\Object
@@ -512,7 +512,7 @@ look like this:
 
 ### Meta-Fields Annotations
 
-There are other meta field for different behaviours of elasticsearch.
+There are specialized meta fields that introduce different behaviours of elasticsearch.
 Read the dedicated page about meta-field annotations [here](http://docs.ongr.io/ElasticsearchBundle/meta_fields).
 
 > More information about mapping can be found in the [Elasticsearch mapping documentation][3].

Resources/doc/meta_fields.md

@@ -47,32 +47,25 @@ attribute is `class`, where you need to specify class of parent document.
     public $parent;
 ```
 
-### @Ttl (_ttl)
+### @Routing (_routing)
 
-This field allows to configure how long a document should live before it is automatically
-deleted. After you add property with `@Ttl` annotation, TTL feature is automatically enabled. 
+Custom routing patterns can be implemented by specifying a custom routing value per document. 
+The same routing value needs to be provided when getting, deleting, or updating the document.
+It is represented by the `@Routing` annotation. Here is an example of such a field:
 
 ```php     
     /**
-     * @ES\Ttl()
+     * @ES\Routing()
      */
-    public $ttl;
+    public $routing;
 ```
 
-You can set default TTL with optional `default` attribute:
+Forgetting the routing value can lead to a document being indexed on more than one shard. 
+As a safeguard, the _routing field can be configured to make a custom routing value 
+required for all CRUD operations. This can be implemented by setting the `equired` 
+attribute to true (`@ES\Routing(required=true)`).
 
-```php     
-    /**
-     * @ES\Ttl(default="5m")
-     */
-    public $ttl;
-```
-
-Example above sets default TTL to 5 minutes. See Elasticsearch [documentation][2]
-for supported time value formats.
-
-> __Note:__ The current `_ttl` implementation is deprecated by Elasticsearch and
-> might be replaced with a different implementation in a future version.
+More information on routing can be found in the [dedicated docs][2]
 
 [1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-fields.html
-[2]: https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units
+[2]: https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html

Resources/doc/overwriting_bundle.md

@@ -1,3 +1,3 @@
 # Overwriting bundle parts
 
-Will come with v1.1.0 version. Check [milestones](https://github.com/ongr-io/ElasticsearchBundle/milestones) to see a progress with the new versions releases.
+Documentation in progress...

Resources/doc/results_parsing.md

@@ -24,7 +24,7 @@ For all chapters below we will use a data example inserted in the elasticsearch
 
 ## Results iterator
 
-Whenever any search action is performed and `Result::RESULTS_OBJECT` is selected as the result type the `DocumentIterator` will be returned. It has plenty of helper functions to aggregate more efficiently with the results.
+Usually when any search action is performed the `DocumentIterator` will be returned. It has plenty of helper functions to aggregate more efficiently with the results.
 
 
 Lets assume you search the index with:
@@ -34,7 +34,7 @@ Lets assume you search the index with:
 $repo = $this->get('es.manager.default.content');
 $search = $repo->createSearch();
 $termQuery = new MatchAllQuery();
-$results = $repo->execute($search, Result::RESULTS_OBJECT); // Result::RESULTS_OBJECT is the default value
+$results = $repo->findDocuments($search);
 
 ```
 
@@ -68,7 +68,7 @@ cannot be associated with document. You can get document's score from results it
 while iterating:
 
 ```php
-$results = $repository->execute($search);
+$results = $repository->findDocuments($search);
 
 foreach ($results as $document) {
     echo $document->title, $results->getDocumentScore();
@@ -95,9 +95,9 @@ foreach ($results as $document) {
 
 `DocumentIterator` doesn't cache or store generated document object. `Converter` directly returns the instance after it's requested and will generate again if it will be requested.
 
-We highly recommend to `unset()` document instance after you dont need it or manage memory at your own way.
+We highly recommend to `unset()` document instance after you don't need it or manage memory at your own way.
 
-There is a possibility to change the `DocumentIterator` behaviour. Take a look at the [overwriting bundle parts](overwriting_bundle.md).
+There is a possibility to change the `DocumentIterator` behaviour. Take a look at the [overwriting bundle parts](http://docs.ongr.io/ElasticsearchBundle/overwriting_bundle).
 
 ## Aggregations
 
@@ -118,7 +118,7 @@ $brandTermAggregation->addAggregation($avgPriceAggregation);
 $query = new Search();
 $query->addAggregation($brandTermAggregation);
 
-$result = $this->get('es.manager')->execute(['AppBundle:Product'], $query);
+$result = $this->get('es.manager.default.content')->findDocuments($query);
 
 // Build a list of available choices
 $choices = [];

Resources/doc/scan.md

@@ -4,9 +4,9 @@ If the index is huge and in a single request there is not enough to get all reco
 
 > More info about index scanning in [elastic official docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-scroll.html#scroll-scan)
 
-You can scan index with any structured search and do a continious scroll. To execute that kind of search you only need to append a scroll time amount to a `Search` object.
+You can scan index with any structured search and do a continuous scroll. To execute that kind of search you only need to append a scroll time amount to a `Search` object.
 
-> Scan & Scroll doesn't work if the result type is `Repository:RESULTS_ARRAY`.
+> Scan & Scroll doesn't work for `Repository::findArray()` method.
 
 Here's an example with scrolling:
 
@@ -20,7 +20,7 @@ $search->setScroll('10m'); // Scroll time
 $termQuery = new TermQuery('country', 'Lithuania');
 $search->addQuery($termQuery);
 
-$results = $repo->execute($search);
+$results = $repo->findDocuments($search);
 
 foreach ($results as $document) {
 
@@ -32,7 +32,7 @@ foreach ($results as $document) {
 
 Usually result amount will be 10 (if no size set), but if the result type is any iterator, it will do a next request when the results set limit is reached and will continue results scrolling in foreach cycle. You dont have to worry about any scroll ids and how to perform second request, everything is handled automatically.
 
-If you are using `Repository:RESULTS_RAW`, then bundle won't request next iteration and you should do it by yourself. Here's an example how to do it:
+If you are using `findRaw()` method, then bundle won't request next iteration and you should do it by yourself. Here's an example how to do it:
 
 
 ```php
@@ -45,14 +45,14 @@ $search->setScroll('10m'); // Scroll time
 $termQuery = new TermQuery('country', 'Lithuania');
 $search->addQuery($termQuery);
 
-$results = $repo->execute($search, Result::RESULTS_RAW);
+$results = $repo->findRaw($search);
 
 foreach ($results as $raw) {
 
 // Do something with RAW results
 
 }
 
-$nextIteration = $repo->getManager()->scroll($results['_scroll_id'], '10m', Result::RESULTS_RAW);
+$nextIteration = $repo->getManager()->scroll($results['_scroll_id'], '10m');
 
 ```

Resources/doc/search.md

@@ -2,11 +2,24 @@
 
 ## Structured search with DSL
 
-If find functions are not enough, there is a possibility to perform a structured search using [query builder](https://github.com/ongr-io/ElasticsearchDSL). In a nutshell you can do any query or filter that is defined in [Elasticsearch Query DSL documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html).
+If find functions are not enough, there is a possibility to perform a structured search using [query builder](https://github.com/ongr-io/ElasticsearchDSL). In a nutshell you can construct any queries, aggregations, etc. that are defined in [Elasticsearch Query DSL documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html).
 
-To begin with structured search you will need a `Search` object.
+To begin with structured search you will need a `Search` object. You need to add all the queries and other DSL constructs
+to this search object and then perform the search from the repository service. There are three specialized `find` methods
+dedicated for this task and you may choose between depending on your needs:
 
-e.g. We want to search for cities in Lithuania with more than 10K population
+| method            | Return Type                                                                     |
+|:-----------------:|:-------------------------------------------------------------------------------:|
+| `findDocuments()` | Returns an instance of `DocumentIterator`                                       |
+| `findArray()`     | Returns an instance of `ArrayIterator`                                          |
+| `findRaw()`       | Returns an array of raw results with unaltered elasticsearch response structure | 
+
+For the majority of cases, you will be using `findDocuments` that returns an iterator with hydrated documents. In addition
+it provides a convenient way of handling aggregations, that can be accessed via `getAggregations()` method.
+
+### Simple Example
+
+In this example we will search for cities in Lithuania with more than 10K population
 
 ```php
 
@@ -19,7 +32,7 @@ $search->addQuery($termQuery);
 $rangeQuery = new RangeQuery('population', ['from' => 10000]);
 $search->addQuery($rangeQuery);
 
-$results = $repo->execute($search);
+$results = $repo->findDocuments($search);
 
 ```
 
@@ -54,7 +67,8 @@ It will construct a query:
 
 > Important: by default result size in elasticsearch is 10, if you need more set size to your needs.
 
-Setting size or offset is to the search is very easy, because it has getters and setters for these attributes. Therefore to set size all you need to do is to write
+Setting size or offset is to the search is very easy, because it has getters and setters for these attributes. 
+Therefore to set size all you need to do is to write
 
 ```php
 
@@ -66,14 +80,17 @@ Similarly other properties like Scroll, Timeout, MinScore and more can be define
 
 For more query and filter examples take a look at the [Elasticsearch DSL library docs](https://github.com/ongr-io/ElasticsearchDSL/blob/master/docs/index.md). We covered all examples that we found in [Elasticsearch Query DSL documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) how to cover in object oriented way.
 
-> The results parsing is the same like in the find functions.
-
 ## Searching in Multiple Types
 
-Previous section showed how to search in single type using repository. In some
-cases you might need to search multiple types at once. In order to do that you
-can use manager's `execute()` method (actually repository's `execute()` is just
-a proxy for this method).
+Previous example illustrated the usual case scenario of performing a search in a single type.
+However if you should ever find yourself in a rear situation where a search needs to be performed
+on several types at once, you can use a specific `search` method in manager, that accepts an 
+array with the names of types on which the search needs to be performed. 
+ 
+However, unlike some of the `find` functions in repository this method returns only the raw results,
+therefore the use of this method should be minimal and only when needed.
+
+### Example of searching in multiple types
 
 Lets say you have `City` and `State` documents with `title` field. Search all
 cities and states with title "Indiana":
@@ -85,11 +102,11 @@ $search->addQuery(new TermQuery('title', 'Indiana'));
 $results = $manager->execute(
     // Array of documents representing different types
     ['AppBundle:City', 'AppBundle:State'], 
-    $search
+    $search->toArray()
 );
 ```
 
-This example returns an iterator with all matching documents.
+> Notice, that the second argument needs to be an array, not a `Search` instance.
 
 ## Results count