Merge branch '2.0'

Author: dunglas

core/content-negotiation.md

@@ -68,6 +68,107 @@ API Platform Core will automatically call the serializer with your defined forma
 as `format` parameter during the deserialization process. Then it will return the result to the client with the asked MIME
 type using its built-in responder.
 
+
+## Writing a Custom Normalizer
+
+Using composition is the recommended way to implement a custom normalizer. You can use the following template to start with your
+own implementation of `CustomItemNormalizer`:
+
+
+```yaml
+# app/config/services.yml
+
+services:
+    app.custom_item_normalizer:
+        public: false
+        class: AppBundle\Serializer\CustomItemNormalizer
+        arguments: [ '@api_platform.serializer.normalizer.item' ]
+        tags: [ { name: serializer.normalizer } ]
+```
+
+```php
+<?php
+
+// src/AppBundle/Serializer/CustomItemNormalizer.php
+
+namespace AppBundle\Serializer;
+
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+class CustomItemNormalizer implements NormalizerInterface, DenormalizerInterface
+{
+    private $normalizer;
+
+    public function __construct(NormalizerInterface $normalizer)
+    {
+        if (!$normalizer instanceof DenormalizerInterface) {
+            throw new \InvalidArgumentException('The normalizer must implement the DenormalizerInterface');
+        }
+
+        $this->normalizer = $normalizer;
+    }
+
+    public function denormalize($data, $class, $format = null, array $context = [])
+    {
+        return $this->normalizer->denormalize($data, $class, $format, $context);
+    }
+
+    public function supportsDenormalization($data, $type, $format = null)
+    {
+        return $this->normalizer->supportsDenormalization($data, $type, $format);
+    }
+
+    public function normalize($object, $format = null, array $context = [])
+    {
+        return $this->normalizer->normalize($object, $format, $context);
+    }
+
+    public function supportsNormalization($data, $format = null)
+    {
+        return $this->normalizer->supportsNormalization($data, $format);
+    }
+}
+```
+
+For example if you want to make the `csv` format to work for even complex entities with a lot of hierarchy, you have
+to flatten or remove too complex relations:
+
+```php
+<?php
+
+// src/AppBundle/Serializer/CustomItemNormalizer.php
+
+namespace AppBundle\Serializer;
+
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+class CustomItemNormalizer implements NormalizerInterface, DenormalizerInterface
+{
+    // ...
+
+    public function normalize($object, $format = null, array $context = [])
+    {
+        $result = $this->normalizer->normalize($object, $format, $context);
+
+        if ('csv' !== $format || !is_array($result)) {
+            return $result;
+        }
+
+        foreach ($result as $key => $value) {
+            if (is_array($value) && array_keys(array_keys($value)) === array_keys($value)) {
+                unset($result[$key]);
+            }
+        }
+
+        return $result;
+    }
+    
+    // ...
+}
+```
+
 Previous chapter: [The Event System](events.md)
 
 Next chapter: [Using External JSON-LD Vocabularies](external-vocabularies.md)

core/data-providers.md

@@ -17,8 +17,8 @@ For a given resource, you can implement two kind of interfaces:
 * the [`ItemDataProviderInterface`](https://github.com/api-platform/core/blob/master/src/DataProvider/ItemDataProviderInterface.php)
   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)).
+In the following examples we will create custom data providers for an entity 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
 
@@ -66,8 +66,8 @@ services:
 ```
 
 Tagging the service with the tag `api_platform.collection_data_provider` will enable API Platform Core to automatically
-register and use this data provider. The optional attribute `priority` allows to define the order in wich are called the
-data providers. The first data provider not throwing a `ApiPlatform\Core\Exception\ResourceClassNotSupportedException`
+register and use this data provider. The optional attribute `priority` allows to define the order in which the
+data providers are called. The first data provider not throwing a `ApiPlatform\Core\Exception\ResourceClassNotSupportedException`
 will be used.
 
 ## Custom Item Data Provider

core/events.md

@@ -40,7 +40,7 @@ final class BookMailSubscriber implements EventSubscriberInterface
     public static function getSubscribedEvents()
     {
         return [
-            KernelEvents::VIEW => [['sendMail', EventPriorities::POST_WRITE]],
+            KernelEvents::VIEW => ['sendMail', EventPriorities::POST_WRITE],
         ];
     }
 

core/filters.md

@@ -707,9 +707,9 @@ use Symfony\Component\HttpFoundation\Request;
 
 final class CustomOrderFilter extends OrderFilter
 {
-    protected function extractProperties(Request $request)
+    protected function extractProperties(Request $request): array
     {
-        $filter = $request->query->get('filter[order]', []);
+        return $request->query->get('filter[order]', []);
     }
 }
 ```

core/form-data.md

@@ -58,6 +58,11 @@ final class DeserializeListener
             return;
         }
         $context = $this->serializerContextBuilder->createFromRequest($request, false, $attributes);
+        $populated = $request->attributes->get('data');
+        if (null !== $populated) {
+            $context['object_to_populate'] = $populated;
+        }
+        
         $data = $request->request->all();
         $object = $this->denormalizer->denormalize($data, $attributes['resource_class'], null, $context);
         $request->attributes->set('data', $object);

core/operations.md

@@ -86,7 +86,10 @@ AppBundle\Entity\Book:
 <!-- 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\Book">
         <itemOperations>
             <itemOperation name="get">
@@ -153,7 +156,10 @@ AppBundle\Entity\Book:
 <!-- 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\Book">
         <itemOperations>
             <itemOperation name="get">
@@ -235,7 +241,10 @@ AppBundle\Entity\Book:
 <!-- 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\Book">
         <itemOperations>
             <itemOperation name="get">
@@ -306,7 +315,7 @@ together.
 Here we consider that DunglasActionBundle is installed (the default when using the API Platform distribution). This
 action will be automatically registered as a service (the service name is the same as the class name: `AppBundle\Action\BookSpecial`).
 
-API Platform automatically retrieve the appropriate PHP entity then then deserializes it, and for `POST` and `PUT` requests
+API Platform automatically retrieves the appropriate PHP entity then deserializes it, and for `POST` and `PUT` requests
 updates the entity with data provided by the user.
 
 Services (`$myService` here) are automatically injected thanks to the autowiring feature. You can type-hint any service

core/pagination.md

@@ -52,10 +52,9 @@ api_platform:
 
 ## Disabling the Pagination
 
-Paginating collection is generally accepted as a good practice. It also allows browsing large collections without to much
+Paginating collections is generally accepted as a good practice. It allows browsing large collections without too much
 overhead as well as preventing [DOS attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack).
-It allows to browse large collections and prevent. However, for small collections, it can be convenient to fully disable
-the pagination.
+However, for small collections, it can be convenient to fully disable the pagination.
 
 ### Globally
 

core/serialization-groups-and-relations.md

@@ -334,7 +334,7 @@ final class BookContextBuilder implements SerializerContextBuilderInterface
         $context = $this->decorated->createFromRequest($request, $normalization, $extractedAttributes);
         $subject = $request->attributes->get('data');
 
-        if ($subject instanceof Book && $this->authorizationChecker->isGranted('ROLE_ADMIN') && false === $normalization) {
+        if ($subject instanceof Book && isset($context['groups']) && $this->authorizationChecker->isGranted('ROLE_ADMIN') && false === $normalization) {
             $context['groups'][] = 'admin_input';
         }
 

distribution/index.md

@@ -48,7 +48,7 @@ several pre-configured and ready-use services with everything needed to run API
 | nginx   | An HTTP server provided by Nginx 1.11                         | 8080
 | varnish | An HTTP cache provided by Varnish 4.1                         | 80
 
-Start by [downloading the API Platform Standard Edition archive](https://api.github.com/repos/api-platform/api-platform/zipball) and extract its content.
+Start by [downloading the API Platform Standard Edition archive](https://github.com/api-platform/api-platform/releases/latest) and extract its content.
 The resulting directory contains an empty API Platform project structure. You will add your own code and configuration inside
 it.
 Then, if you do not already have Docker on your computer, [it's the right time to install it](https://www.docker.com/products/overview#/install_the_platform).
@@ -99,7 +99,7 @@ ORM and its bridge supports major RDBMS including MySQL, PostgreSQL, SQLite, SQL
 Instead of using Docker, API Platform can also be installed on the local machine using [Composer](https://getcomposer.org/):
 
     $ composer create-project api-platform/api-platform bookshop-api
-    
+
 Then, enter the project folder, create the database and its schema:  
 
     $ cd bookshop-api
@@ -443,12 +443,12 @@ Oops, we missed to add the title. But submit the request anyway. You should get
 
 Did you notice that the error was automatically serialized in JSON-LD and respect the Hydra Core vocabulary for errors?
 It allows the client to easily extract useful information from the error. Anyway, it's bad to get a SQL error when submitting
-a request. It means that we doesn't use a valid input, and [it's a very bad and dangerous practice](https://www.owasp.org/index.php/Input_Validation_Cheat_Sheet).
+a request. It means that we didn't use a valid input, and [it's a very bad and dangerous practice](https://www.owasp.org/index.php/Input_Validation_Cheat_Sheet).
 
 API Platform comes with a bridge with [the Symfony Validator Component](http://symfony.com/doc/current/validation.html).
 Adding some of [its numerous validation constraints](http://symfony.com/doc/current/validation.html#supported-constraints)
 (or [creating custom ones](http://symfony.com/doc/current/validation/custom_constraint.html)) to our entities is enough
-to get validate user submitted data. Let's add some validation rules to our data model:
+to validate user submitted data. Let's add some validation rules to our data model:
 
 ```php
 <?php

index.md

@@ -56,6 +56,7 @@
     1.  [Enabling Several Formats](core/content-negotiation.md#enabling-several-formats)
     2.  [Registering a Custom Serializer](core/content-negotiation.md#registering-a-custom-serializer)
     3.  [Creating a Responder](core/content-negotiation.md#creating-a-responder)
+    4.  [Writing a Custom Normalizer](core/content-negotiation.md#writing-a-custom-normalizer)
 11. [Using External JSON-LD Vocabularies](core/external-vocabularies.md)
 12. [Extending JSON-LD context](core/extending-jsonld-context.md)
 13. [Data Providers](core/data-providers.md)

schema-generator/configuration.md

@@ -260,7 +260,7 @@ author: "Kévin Dunglas <[email protected]>"
 ## Disabling Generators and Creating Custom Ones
 
 By default, all generators except `DunglasJsonLdApi` (API Platform v1) and `SerializerGroups` are enabled.
-You can specify the list of generators to use with the `generators` option.
+You can specify the list of generators to use with the `annotationGenerators` option.
 
 Example (enabling only the PHPDoc generator):
 
@@ -283,8 +283,7 @@ annotationGenerators:
 
 ## Disabling `id` Generator
 
-By default, the generator add a property called `id` not provided by Schema.org. This useful when using generated entity
-with an ORM or an ODM.
+By default, the generator adds a property called `id` not provided by Schema.org. This may be useful when generating an entity for use with an ORM or an ODM.
 This behavior can be disabled with the following setting:
 
 ```yaml