Merge pull request #1 from api-platform/master

Update

Author: Timherlaud

core/configuration.md

@@ -22,6 +22,9 @@ api_platform:
     # Specify a name converter to use.
     name_converter: ~
 
+    # Specify a name for the folder within bundle that contain api resources.
+    api_resources_directory: 'Entity'
+
     eager_loading:
         # To enable or disable eager loading.
         enabled: true

core/data-providers.md

@@ -18,6 +18,7 @@ For a given resource, you can implement two kind of interfaces:
   is used when fetching items.
 
 In the following examples we will create custom data providers for an entity class class called `AppBundle\Entity\BlogPost`.
+Note, that if your entity is not doctrine-related, you need to flag the identifier property by using `@ApiProperty(identifiier=true)` for things to work properly (see also [Entity Identifier Case](serialization-groups-and-relations.md#entity-identifier-case)).
 
 ## Custom Collection Data Provider
 

core/filters.md

@@ -152,7 +152,7 @@ constant directly.
 
 The boolean filter allows you to search on boolean fields and values.
 
-Syntax: `?property=[on|off|true|false|0|1]`
+Syntax: `?property=[true|false|1|0]`
 
 You can either use TRUE or true, the parameters are case insensitive.
 
@@ -422,15 +422,105 @@ It means that the filter will be **silently** ignored if the property:
 Custom filters can be written by implementing the `ApiPlatform\Core\Api\FilterInterface`
 interface.
 
-If you use [custom data providers](data-providers.md), they must support filtering and be aware of active filters to work
-properly.
+API Platform provides a convenient way to create Doctrine ORM filters. If you use [custom data providers](data-providers.md),
+you can still create filters by implementing the previously mentioned interface, but - as API Platform isn't aware of your
+persistence system's internals - you have to create the filtering logic by yourself.
 
 ### Creating Custom Doctrine ORM Filters
 
-Doctrine ORM filters must implement the `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\FilterInterface`.
-They can interact directly with the Doctrine `QueryBuilder`.
+Doctrine filters can access to the HTTP request (Symfony's `Request` object) and to the `QueryBuilder` instance used to
+retrieve data from the database. They are only applied to collections. If you want to deal with the DQL query generated
+to retrieve items, or don't need to access the HTTP request, [extensions](extensions.md) are the way to go.
 
-A convenient abstract class is also shipped with the bundle: `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\AbstractFilter`
+A Doctrine ORM filter is basically a class implementing the `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\FilterInterface`.
+API Platform includes a convenient abstract class implementing this interface and providing utility methods: `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\AbstractFilter`
+
+In the following example, we create a class to filter a collection by applying a regexp to a property. The `REGEXP` DQL
+function used in this example can be found in the [`DoctrineExtensions`](https://github.com/beberlei/DoctrineExtensions)
+library. This library must be properly installed and registered to use this example (works only with MySQL).
+
+```php
+<?php
+
+// src/AppBundle/Filter/RegexpFilter.php
+
+namespace AppBundle\Filter;
+
+use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\AbstractFilter;
+use ApiPlatform\Core\Bridge\Doctrine\Orm\Util\QueryNameGeneratorInterface;
+use Doctrine\ORM\QueryBuilder;
+
+final class RegexpFilter extends AbstractFilter
+{
+    protected function filterProperty(string $property, $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, string $operationName = null)
+    {
+        $parameterName = $queryNameGenerator->generateParameterName($property); // Generate a unique parameter name to avoid collisions with other filters
+        $queryBuilder
+            ->andWhere(sprintf('REGEXP(o.%s, :%s) = 1', $property, $parameterName))
+            ->setParameter($parameterName, $value);
+    }
+
+    // This function is only used to hook in documentation generators (supported by Swagger and Hydra)
+    public function getDescription(string $resourceClass): array
+    {
+        $description = [];
+        foreach ($this->properties as $property => $strategy) {
+            $description['regexp_'.$property] = [
+                'property' => $property,
+                'type' => 'string',
+                'required' => false,
+                'swagger' => ['description' => 'Filter using a regex. This will appear in the Swagger documentation!'],
+            ];
+        }
+
+        return $description;
+    }
+}
+```
+
+Then, register this filter as a service:
+
+```yaml
+services:
+    'AppBundle\Filter\RegexpFilter':
+        class: 'AppBundle\Filter\RegexpFilter'
+        autowire: true # See the next example for a plain old definition
+        tags: [ { name: 'api_platform.filter', id: 'regexp' } ]
+```
+
+In the previous example, the filter can be applied on any property. However, thanks to the `AbstractFilter` class,
+it can also be enabled for some properties:
+
+```yaml
+services:
+    'AppBundle\Filter\RegexpFilter':
+        class: 'AppBundle\Filter\RegexpFilter'
+        arguments: [ '@doctrine', '@request_stack', '@?logger', { email: ~, anOtherProperty: ~ } ]
+        tags: [ { name: 'api_platform.filter', id: 'regexp' } ]
+```
+
+Finally, add this filter to resources you want to be filtered:
+
+```php
+<?php
+
+// src/AppBundle/Entity/Offer.php
+
+namespace AppBundle\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(attributes={"filters"={"regexp"}})
+ */
+class Offer
+{
+    // ...
+}
+```
+
+You can now enable this filter using URLs like `http://example.com/offers?regexp_email=^[FOO]`. This new filter will also
+appear in Swagger and Hydra documentations.
 
 ### Overriding Extraction of Properties from the Request
 

core/form-data.md

@@ -102,7 +102,7 @@ class AppBundle extends Bundle
         $container->addCompilerPass(new class implements CompilerPassInterface {
             public function process(ContainerBuilder $container) {
                 $container
-                    ->findDefinition('api_platform.listener.request.deserialize');
+                    ->findDefinition('api_platform.listener.request.deserialize')
                     ->clearTags();
             }
         });

core/fosuser-bundle.md

@@ -10,7 +10,7 @@ You need to use serialization groups to hide some properties like `plainPassword
 shown are handled with the [`normalization_context`](serialization-groups-and-relations.md#normalization), while the properties
 you can modify are handled with [`denormalization_context`](serialization-groups-and-relations.md#denormalization).
 
-First register the following service:
+Create your User entity with serialization groups:
 
 ```php
 <?php

core/getting-started.md

@@ -56,7 +56,7 @@ API Platform Core is able to automatically expose entities mapped as "API resour
 operations.
 To expose your entities, you can use Docblock annotations, XML and YAML configuration files.
 
-Here is an example of entities mapped using annotations which will be exposed trough a REST API:
+Here is an example of entities mapped using annotations which will be exposed through a REST API:
 
 ```php
 <?php
@@ -138,7 +138,7 @@ class Offer
 }
 ```
 
-It is the minimal configuration required to expose `Product` and `Offer` entities as JSON-LD documents trough an hypermedia
+It is the minimal configuration required to expose `Product` and `Offer` entities as JSON-LD documents through an hypermedia
 web API.
 
 If you are familiar with the Symfony ecosystem, you noticed that entity classes are also mapped with Doctrine ORM annotations
@@ -173,7 +173,10 @@ As an alternative to annotations, you can map entity classes using XML or YAML:
 <!-- src/AppBundle/Resources/config/api_resources/resources.xml -->
 
 <?xml version="1.0" encoding="UTF-8" ?>
-<resources>
+<resources xmlns="https://api-platform.com/schema/metadata"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="https://api-platform.com/schema/metadata
+           https://api-platform.com/schema/metadata/metadata-2.0.xsd">
     <resource class="AppBundle\Entity\Product" />
     <resource
         class="AppBundle\Entity\Offer"

core/jwt.md

@@ -1,6 +1,6 @@
 # JWT Authentification
 
-> [JSON Web Token (JWT)](jwt.io) is a JSON-based open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) for creating access tokens that assert some number of claims. For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that he/she is logged in as admin. The tokens are signed by the server's key, so the server is able to verify that the token is legitimate. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context.
+> [JSON Web Token (JWT)](https://jwt.io/) is a JSON-based open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) for creating access tokens that assert some number of claims. For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that he/she is logged in as admin. The tokens are signed by the server's key, so the server is able to verify that the token is legitimate. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context.
 
 [Uncyclopedia](https://en.wikipedia.org/wiki/JSON_Web_Token)
 
@@ -35,13 +35,12 @@ security:
             stateless: true
             anonymous: true
             provider: fos_userbundle
-            form_login:
+            json_login:
                 check_path: /login_check
-                username_parameter: email
-                password_parameter: password
+                username_path: email
+                password_path: password
                 success_handler: lexik_jwt_authentication.handler.authentication_success
                 failure_handler: lexik_jwt_authentication.handler.authentication_failure
-                require_previous_session: false
 
         main:
             pattern:   ^/

core/operations.md

@@ -49,7 +49,8 @@ Operations can be configured using annotations, XML or YAML. In the following ex
 for the `GET` method for both `collectionOperations` and `itemOperations` to create a readonly endpoint.
 
 `itemOperations` and `collectionOperations` are arrays containing a list of operation. Each operation is defined by a key
-corresponding to the name of the operation that can be anything you want and an array of properties as value.
+corresponding to the name of the operation that can be anything you want and an array of properties as value. If an
+empty list of operations is provided, all operations are disabled.
 
 <configurations>
 
@@ -87,12 +88,16 @@ AppBundle\Entity\Book:
 <?xml version="1.0" encoding="UTF-8" ?>
 <resources>
     <resource class="AppBundle\Entity\Book">
-        <itemOperation name="get">
-            <attribute name="method">GET</attribute>
-        </itemOperation>
-        <collectionOperation name="get">
-            <attribute name="method">GET</attribute>
-        </collectionOperation>
+        <itemOperations>
+            <itemOperation name="get">
+                <attribute name="method">GET</attribute>
+            </itemOperation>
+        </itemOperations>
+        <collectionOperations>
+            <collectionOperation name="get">
+                <attribute name="method">GET</attribute>
+            </collectionOperation>
+        </collectionOperations>
     </resource>
 </resources>
 ```
@@ -150,17 +155,19 @@ AppBundle\Entity\Book:
 <?xml version="1.0" encoding="UTF-8" ?>
 <resources>
     <resource class="AppBundle\Entity\Book">
-        <itemOperation name="get">
-            <attribute name="method">GET</attribute>
-            <attribute name="path">/grimoire/{id}</attribute>
-        </itemOperation>
-        <itemOperation name="put">
-            <attribute name="method">PUT</attribute>
-            <attribute name="path">/grimoire/{id}/update</attribute>
-            <attribute name="hydra_context">
-                <attribute name="foo">bar</attribute>
-            </attribute>
-        </itemOperation>
+        <itemOperations>
+            <itemOperation name="get">
+                <attribute name="method">GET</attribute>
+                <attribute name="path">/grimoire/{id}</attribute>
+            </itemOperation>
+            <itemOperation name="put">
+                <attribute name="method">PUT</attribute>
+                <attribute name="path">/grimoire/{id}/update</attribute>
+                <attribute name="hydra_context">
+                    <attribute name="foo">bar</attribute>
+                </attribute>
+            </itemOperation>
+        </itemOperations>
     </resource>
 </resources>
 ```
@@ -230,12 +237,14 @@ AppBundle\Entity\Book:
 <?xml version="1.0" encoding="UTF-8" ?>
 <resources>
     <resource class="AppBundle\Entity\Book">
-        <itemOperation name="get">
-            <attribute name="method">GET</attribute>
-        </itemOperation>
-        <itemOperation name="special">
-            <attribute name="route_name">book_special</attribute>
-        </itemOperation>
+        <itemOperations>
+            <itemOperation name="get">
+                <attribute name="method">GET</attribute>
+            </itemOperation>
+            <itemOperation name="special">
+                <attribute name="route_name">book_special</attribute>
+            </itemOperation>
+        </itemOperations>
     </resource>
 </resources>
 ```

core/performance.md

@@ -22,7 +22,7 @@ Keep in mind that PPM is still in an early stage of development and can cause is
 
 When using the `SearchFilter` and case insensivity, Doctrine will use the `LOWER` SQL function. Depending on your
 driver, you may want to carefully index it by using a [function-based
-index](http://use-the-index-luke.com/sql/where-clause/functions/case-insensitive-search) or it will impact performanc
+index](http://use-the-index-luke.com/sql/where-clause/functions/case-insensitive-search) or it will impact performance
 with a huge collection. [Here are some examples to index LIKE
 filters](http://use-the-index-luke.com/sql/where-clause/searching-for-ranges/like-performance-tuning) depending on your
 database driver.
@@ -36,11 +36,20 @@ Fortunately, Doctrine proposes another approach to remedy this problem: [eager l
 This can easily be enabled for a relation: `@ORM\ManyToOne(fetch="EAGER")`.
 
 By default in API Platform, we made the choice to force eager loading for all relations, with or without the Doctrine
-`fetch` attribute. Thanks to the eager loading [extension](extensions.md).
+`fetch` attribute. Thanks to the eager loading [extension](extensions.md). The `EagerLoadingExtension` will join every
+readable association according to the serialization context. If you want to fetch an association that is not serializable
+you've to bypass `readable` and `readableLink` by using the `fetchEager` attribute on the property declaration, for example:
+
+```php
+/**
+ * @ApiProperty(attributes={"fetchEager": true})
+ */
+ public $foo;
+```
 
 #### Max joins
 
-There is a default restriction with this feature. We allow up to 30 joins per query. Beyond, an 
+There is a default restriction with this feature. We allow up to 30 joins per query. Beyond, an
 `ApiPlatform\Core\Exception\RuntimeException` exception will be thrown but this value can easily be increased with a
 little of configuration:
 
@@ -61,7 +70,7 @@ can be a good solution to fix this issue.
 
 #### Force eager
 
-As mentioned above, by default we force eager loading for all relations. This behaviour can be modified with the 
+As mentioned above, by default we force eager loading for all relations. This behaviour can be modified with the
 configuration in order to apply it only on join relations having the `EAGER` fetch mode:
 
 ```yaml
@@ -117,8 +126,8 @@ class User
 {
     /**
      * @var Address
-     * 
-     * @ORM\ManyToOne(targetEntity="Address", fetch="EAGER") 
+     *
+     * @ORM\ManyToOne(targetEntity="Address", fetch="EAGER")
      */
     public $address;
 
@@ -171,7 +180,7 @@ configuration.
 
 #### Disable eager loading
 
-If for any reason you don't want the eager loading feature, you can turn off it in the configuration:
+If for any reason you don't want the eager loading feature, you can turn it off in the configuration:
 
 ```yaml
 # app/config/config.yaml

core/serialization-groups-and-relations.md

@@ -136,7 +136,7 @@ In the following JSON document, the relation from a book to an author is represe
 ### Normalization
 
 To improve the application's performance, it is sometimes necessary to avoid issuing extra HTTP requests. It is possible
-to embed related objects (or only some of their properties) directly in the parent response trough serialization groups.
+to embed related objects (or only some of their properties) directly in the parent response through serialization groups.
 By using the following serialization groups annotations (`@Groups`), a JSON representation of the author is embedded in
 the book response:
 
@@ -239,7 +239,7 @@ class Book
 
 The following rules apply when denormalizating embedded relations:
 
-* If a `@id` key is present in the embedded resource, the object corresponding to the given URI will be retrieved trough
+* If a `@id` key is present in the embedded resource, the object corresponding to the given URI will be retrieved through
 the data provider and any changes in the embedded relation will be applied to that object.
 * If no `@id` key exists, a new object will be created containing data provided in the embedded JSON document.
 

deployment/docker.md

@@ -7,7 +7,7 @@ stack is shipped with the API Platform distribution.
 To install it, run the following commands (Docker must be installed on your system):
 
     $ docker-compose up -d # Download, build and run Docker images
-    $ docker-compose exec web bin/console doctrine:schema:create # Create the MySQL schema
+    $ docker-compose exec app bin/console doctrine:schema:create # Create the MySQL schema
 
 Your project will be accessible at the URL `http://127.0.0.1`.
 

deployment/heroku.md

@@ -1,7 +1,7 @@
 # Deploying an API Platform App on Heroku
 
 [Heroku](http://heroku.com) is a popular, fast, scalable and reliable *Platform As A Service* (PaaS). As Heroku offers a
-free plan including database support trough [Heroku Postgres](https://www.heroku.com/postgres), it's
+free plan including database support through [Heroku Postgres](https://www.heroku.com/postgres), it's
 a very convenient way to experiment with the API Platform.
 
 The API Platform Heroku integration also supports MySQL databases provided by [the ClearDB add-on](https://addons.heroku.com/cleardb).