Elasticsearch documentation (#717)

* Elasticsearch documentation

* CS

Author: meyerbaptiste

core/configuration.md

@@ -90,6 +90,16 @@ api_platform:
         graphiql:
             enabled: true
 
+    elasticsearch:
+        # To enable or disable Elasticsearch support.
+        enabled: false
+
+        # The hosts to the Elasticsearch nodes.
+        hosts: []
+
+        # The mapping between resource classes and indexes.
+        mapping: []
+
     swagger:
         # The swagger api keys.
         api_keys: []

core/data-providers.md

@@ -1,12 +1,13 @@
 # Data Providers
 
 To retrieve data exposed by the API, API Platform uses classes called **data providers**. A data provider using [Doctrine
-ORM](http://www.doctrine-project.org/projects/orm.html) to retrieve data from a database is included with the library and
-is enabled by default. This data provider natively supports paged collections and filters. It can be used as is and fits
-perfectly with common usages.
+ORM](http://www.doctrine-project.org/projects/orm.html) to retrieve data from a database, a data provider using
+[Doctrine MongoDB ODM](https://www.doctrine-project.org/projects/mongodb-odm.html) to retrieve data from a document
+database, and a data provider using [Elasticsearch-PHP](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/index.html)
+to retrieve data from an Elasticsearch cluster are included with the library. The first one is enabled by default. These
+data providers natively support paged collections and filters. They can be used as is and fits perfectly with common usages.
 
-However, you sometime want to retrieve data from other sources such as another persistence layer, a webservice, ElasticSearch
-or MongoDB.
+However, you sometime want to retrieve data from other sources such as another persistence layer or a webservice.
 Custom data providers can be used to do so. A project can include as many data providers as it needs. The first able to
 retrieve data for a given resource will be used.
 

core/default-order.md

@@ -24,6 +24,8 @@ class Book
      * ...
      */
     public $foo;
+    
+    // ...
 }
 ```
 
@@ -54,6 +56,8 @@ class Book
      * ...
      */
     public $bar;
+    
+    // ...
 }
 ```
 
@@ -78,5 +82,7 @@ class Book
      * @var User
      */
     public $author;
+    
+    // ...
 }
 ```

core/deprecations.md

@@ -93,6 +93,8 @@ class Review
      * @ApiProperty(deprecationReason="Use the rating property instead")
      */
     public $letter;
+    
+    // ...
 }
 ```
 

core/elasticsearch.md

@@ -0,0 +1,273 @@
+# Elasticsearch Support
+
+## Overview
+
+Elasticsearch is a distributed, RESTful search and analytics engine capable of solving a growing number of use cases:
+application search, security analytics, metrics, logging, etc.
+
+API Platform comes natively with the **reading** support for Elasticsearch. It uses internally the official PHP client
+for Elasticsearch: [Elasticsearch-PHP](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/index.html).
+
+Be careful, API Platform only supports Elasticsearch >= 6.5.0.
+
+## Enabling reading support
+
+To enable the reading support for Elasticsearch, simply require the Elasticsearch-PHP package using Composer:
+
+    $ composer require elasticsearch/elasticsearch:^6.0
+    
+Then, enable it inside the API Platform configuration:
+
+```yaml
+# api/config/packages/api_platform.yaml
+parameters:
+    # ...
+    env(ELASTICSEARCH_HOST): 'http://localhost:9200'
+
+api_platform:
+    # ...
+
+    mapping:
+        paths: ['%kernel.project_dir%/src/Model']
+
+    elasticsearch:
+        hosts: ['%env(ELASTICSEARCH_HOST)%']
+
+    #...
+```
+
+## Creating models
+
+First of all, API Platform follows the best practices of Elasticsearch:
+* a single index per resource should be used because Elasticsearch is going to [drop support for index types and will allow only a single type per
+index](https://www.elastic.co/guide/en/elasticsearch/reference/current/removal-of-types.html);
+* index name should be the short resource name in lower case;
+* the default `_doc` type should be used;
+* all fields should be lower case and should use snake case for combining words.
+
+This involves having mappings and models which absolutely match each other.
+
+Here is an example of mappings for 2 resources, `User` and `Tweet`, and their models:
+
+```json
+PUT user
+{
+  "mappings": {
+    "_doc": {
+      "properties": {
+        "id": {
+          "type": "keyword"
+        },
+        "gender": {
+          "type": "keyword"
+        },
+        "age": {
+          "type": "integer"
+        },
+        "first_name": {
+          "type": "text"
+        },
+        "last_name": {
+          "type": "text"
+        },
+        "tweets": {
+          "type": "nested",
+          "properties": {
+            "id": {
+              "type": "keyword"
+            },
+            "date": {
+              "type": "date",
+              "format": "yyyy-MM-dd HH:mm:ss"
+            },
+            "message": {
+              "type": "text"
+            }
+          },
+          "dynamic": "strict"
+        }
+      },
+      "dynamic": "strict"
+    }
+  }
+}
+```
+
+```json
+PUT tweet
+{
+  "mappings": {
+    "_doc": {
+      "properties": {
+        "id": {
+          "type": "keyword"
+        },
+        "author": {
+          "properties": {
+            "id": {
+              "type": "keyword"
+            },
+            "gender": {
+              "type": "keyword"
+            },
+            "age": {
+              "type": "integer"
+            },
+            "first_name": {
+              "type": "text"
+            },
+            "last_name": {
+              "type": "text"
+            }
+          },
+          "dynamic": "strict"
+        },
+        "date": {
+          "type": "date",
+          "format": "yyyy-MM-dd HH:mm:ss"
+        },
+        "message": {
+          "type": "text"
+        }
+      },
+      "dynamic": "strict"
+    }
+  }
+}
+```
+
+```php
+<?php
+// api/src/Model/User.php
+
+namespace App\Model;
+
+use ApiPlatform\Core\Annotation\ApiProperty;
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource
+ */
+class User
+{
+    /**
+     * @ApiProperty(identifier=true)
+     *
+     * @var string
+     */
+    public $id;
+
+    /**
+     * @var string
+     */
+    public $gender;
+
+    /**
+     * @var int
+     */
+    public $age;
+
+    /**
+     * @var string
+     */
+    public $firstName;
+
+    /**
+     * @var string
+     */
+    public $lastName;
+
+    /**
+     * @var Tweet[]
+     */
+    public $tweets = [];
+}
+```
+
+```php
+<?php
+// api/src/Model/Tweet.php
+
+namespace App\Model;
+
+use ApiPlatform\Core\Annotation\ApiProperty;
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource
+ */
+class Tweet
+{
+    /**
+     * @ApiProperty(identifier=true)
+     *
+     * @var string
+     */
+    public $id;
+
+    /**
+     * @var User
+     */
+    public $author;
+
+    /**
+     * @var \DateTimeInterface
+     */
+    public $date;
+
+    /**
+     * @var string
+     */
+    public $message;
+}
+```
+
+API Platform will automatically disable write operations and snake case document fields will automatically be converted to 
+camel case object properties during serialization.
+
+Keep in mind that it is your responsibility to populate your Elasticsearch index. To do so, you can use [Logstash](https://www.elastic.co/products/logstash),
+a custom [data persister](data-persisters.md#creating-a-custom-data-persister) or any other mechanism that fits for your
+project (such as an [ETL](https://en.wikipedia.org/wiki/Extract,_transform,_load)).
+
+You're done! The API is now ready to use.
+
+### Creating custom mapping
+
+If you don't follow the Elasticsearch recommendations, you may want a custom mapping between API Platform resources and
+Elasticsearch indexes/types.
+
+For example, consider an index being similar to a database in an SQL database and a type being equivalent to a table.
+So the `User` and `Tweet` resources of the previous example would become `user` and `tweet` types in an index named `app`:
+
+```yaml
+# api/config/packages/api_platform.yaml
+parameters:
+    # ...
+    env(ELASTICSEARCH_HOST): 'http://localhost:9200'
+
+api_platform:
+    # ...
+    
+    mapping:
+        paths: ['%kernel.project_dir%/src/Model']
+
+    elasticsearch:
+        hosts: ['%env(ELASTICSEARCH_HOST)%']
+        mapping:
+            App\Model\User:
+                index: app
+                type: user
+            App\Model\Tweet:
+                index: app
+                type: tweet
+
+    #...
+```
+
+## Filtering
+
+See how to use Elasticsearch filters and how to create Elasticsearch custom filters in [the Filters chapter](filters.md).
+
+## Creating custom extensions
+
+See how to create Elasticsearch custom extensions in [the Extensions chapter](extensions.md).

core/errors.md

@@ -15,7 +15,7 @@ configure API Platform to convert it to a `404 Not Found` error:
 
 ```php
 <?php
-// src/Exception/ProductNotFoundException.php
+// api/src/Exception/ProductNotFoundException.php
 
 namespace App\Exception;
 
@@ -26,7 +26,7 @@ final class ProductNotFoundException extends \Exception
 
 ```php
 <?php
-// src/EventSubscriber/CartManager.php
+// api/src/EventSubscriber/CartManager.php
 
 namespace App\EventSubscriber;
 

core/extending-jsonld-context.md

@@ -37,6 +37,8 @@ class Book
      * )
      */
     public $name;
+    
+    // ...
 }
 ```