Merge branch '2.1'

Author: dunglas

.travis.yml

@@ -0,0 +1,29 @@
+language: node
+
+cache:
+  yarn: true
+
+env:
+  global:
+    secure: gjiWHIgNjLXuEFmLiepiOTHOuauHfeKHutrE0sBwFZUQzP9FoGTZzJub1z8/vm+hhygA+TZbB0iclygHyNrXCkZyNdnZXChXl4iPdYqY3OARPOAbQff16+/XSUDsZ/Ok1etdb3kKor1R4rBt/WywBvXmmdggumTA3yT5ExI+dyomdONo4yMUZ7g1la0ehMEzGqyVjt0nUW31PN3l6dI1qgigHCuotSrrpWP6fTXuUh5l6YA7KXb/V1hJxaGENLz1Cdfk0sF66e4KsV/DX6JZSqpvdqVB8OTPU+si511yJtGS8OeuLs4RqmXMLrY/ChCodlYnfCE+NleBFpUnCVqth/RDRh7LvplUJlpsXNcfyoA3mOFmZa0euOMCqJ3qwESz802Y9c5oN63hn2OUF/raFDc3SMMC86FFHxwyYjz5+yzXYupnFNj39NKdQ1v1KBbY8BD8UT8RU3mlu4/3LRz0tSamREHj3pGgBmvgUZfUE1dMngeaZjOmBaIZH8TnKQ75CvfnoT+LJnZo6g9g4uwz6jtaIziSMZ0OW/95nF8yx+xONbHEtt5ex5M09NOFsN2vB2bcUAgIjyGrmmNLQadwJyQv557IGPEE5CyGhJpXh9XZ+WMw2vO45MOw4sQPkARF6OJkMteqFc2NLXMOQJ07EScbgEKR/9VOcyxIk/7a7nc=
+
+install:
+  - cd ..
+  - git clone https://github.com/api-platform/website.git
+  - cd website
+  - yarn install
+  - ln -s $TRAVIS_BUILD_DIR src/pages/docs
+
+script:
+  - cd $TRAVIS_BUILD_DIR/../website
+  - bin/generate-nav
+  - yarn gatsby build
+
+deploy:
+  provider: pages
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN
+  local_dir: $TRAVIS_BUILD_DIR/../website/public
+  fqdn: api-platform.com
+  on:
+    branch: 2.1

admin/getting-started.md

@@ -11,6 +11,10 @@ Then, create a new React application for your admin:
 
     $ create-react-app my-admin
 
+Now, go to the newly created `my-admin` directory:
+
+    $ cd my-admin
+
 React and React DOM will be directly provided as dependencies of Admin On REST. As having different versions of React
 causes issues, remove `react` and `react-dom` from the `dependencies` section of the generated `package.json` file:
 
@@ -34,6 +38,12 @@ import { HydraAdmin } from '@api-platform/admin';
 export default () => <HydraAdmin entrypoint="https://demo.api-platform.com"/>; // Replace with your own API entrypoint
 ```
 
+Be sure to make your API send proper [CORS HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to allow the admin's domain to access it. To do so, update the value of the `cors_allow_origin` parameter in `app/config/parameters.yml` (it will be `http://localhost:3000` by default).
+
+Clear the cache to apply this change:
+
+    $ docker-compose exec app bin/console cache:clear --env=prod
+
 Your new administration interface is ready! Type `yarn start` to try it!
 
 Note: if you don't want to hardcode the API URL, you can [use an environment variable](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-custom-environment-variables).
@@ -51,26 +61,30 @@ In the following example, we change components used for the `description` proper
 import React from 'react';
 import { RichTextField } from 'admin-on-rest';
 import RichTextInput from 'aor-rich-text-input';
-import HydraAdmin from 'api-platform-admin/lib/hydra/HydraAdmin';
-import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
+import { HydraAdmin } from '@api-platform/admin';
+import parseHydraDocumentation from '@api-platform/api-doc-parser/lib/hydra/parseHydraDocumentation';
 
 const entrypoint = 'https://demo.api-platform.com';
 
-const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
-  .then(api => {
-    api.resources.map(resource => {
-      const books = api.resources.find(r => 'books' === r.name);
-      books.fields.find(f => 'description' === f.name).fieldComponent = <RichTextField source="description" key="description"/>;
-      books.fields.find(f => 'description' === f.name).inputComponent = <RichTextInput source="description" key="description"/>;
+const myApiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
+  .then( ({ api }) => {
+    const books = api.resources.find(({ name }) => 'books' === name);
+    const description = books.fields.find(f => 'description' === f.name);
 
-      return resource;
-    });
+    description.input = props => (
+      <RichTextInput {...props} source="description" />
+    );
 
-    return api;
+    description.input.defaultProps = {
+      addField: true,
+      addLabel: true
+    };
+
+    return { api };
   })
 ;
 
-export default (props) => <HydraAdmin apiDocumentationParser={apiDocumentationParser} entrypoint={entrypoint}/>;
+export default (props) => <HydraAdmin apiDocumentationParser={myApiDocumentationParser} entrypoint={entrypoint}/>;
 ```
 
 The `fieldComponent` property of the `Field` class allows to set the component used to render a property in list and show screens.
@@ -90,13 +104,28 @@ In the following example, we will:
 ```javascript
 import { FunctionField, ImageField, ImageInput } from 'admin-on-rest/lib/mui';
 import React from 'react';
-import HydraAdmin from 'api-platform-admin/lib/hydra/HydraAdmin';
-import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
+import { RichTextField } from 'admin-on-rest';
+import RichTextInput from 'aor-rich-text-input';
+import { HydraAdmin } from '@api-platform/admin';
+import parseHydraDocumentation from '@api-platform/api-doc-parser/lib/hydra/parseHydraDocumentation';
 
 const entrypoint = 'https://demo.api-platform.com';
 
-const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
-  .then(api => {
+const myApiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
+  .then( ({ api }) => {
+
+    const books = api.resources.find(({ name }) => 'books' === name);
+    const description = books.fields.find(f => 'description' === f.name);
+
+    description.input = props => (
+      <RichTextInput {...props} source="description" />
+    );
+
+    description.input.defaultProps = {
+      addField: true,
+      addLabel: true,
+    };
+
     api.resources.map(resource => {
       if ('http://schema.org/ImageObject' === resource.id) {
         resource.fields.map(field => {
@@ -143,11 +172,11 @@ const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
       return resource;
     });
 
-    return api;
+    return { api };
   })
 ;
 
-export default (props) => <HydraAdmin apiDocumentationParser={apiDocumentationParser} entrypoint={entrypoint}/>;
+export default (props) => <HydraAdmin apiDocumentationParser={myApiDocumentationParser} entrypoint={entrypoint}/>;
 ```
 
 __Note__: In this example, we choose to send the file via a multi-part form data, but you are totally free to use another solution (like `base64`). But keep in mind that multi-part form data is the most efficient solution.
@@ -168,15 +197,17 @@ export default class extends Component {
   state = {api: null};
 
   componentDidMount() {
-    parseHydraDocumentation(entrypoint).then(api => {
+    parseHydraDocumentation(entrypoint).then( ({ api }) =>  => {
       const books = api.resources.find(r => 'books' === r.name);
 
       books.writableFields.find(f => 'description' === f.name).inputProps = {
         validate: value => value.length >= 30 ? undefined : 'Minimum length: 30';
       };
 
       this.setState({api: api});
-    })
+      
+      return { api };
+    });
   }
 
   render() {

core/configuration.md

@@ -21,9 +21,6 @@ api_platform:
     # Specify a path name generator to use.
     path_segment_name_generator: 'api_platform.path_segment_name_generator.underscore'
 
-    # 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/extensions.md

@@ -69,14 +69,14 @@ use AppBundle\Entity\Offer;
 use AppBundle\Entity\User;
 use Doctrine\ORM\QueryBuilder;
 use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
-use Symfony\Component\Security\Core\Authorization\AuthorizationChecker;
+use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
 
 final class CurrentUserExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
 {
     private $tokenStorage;
     private $authorizationChecker;
 
-    public function __construct(TokenStorageInterface $tokenStorage, AuthorizationChecker $checker)
+    public function __construct(TokenStorageInterface $tokenStorage, AuthorizationCheckerInterface $checker)
     {
         $this->tokenStorage = $tokenStorage;
         $this->authorizationChecker = $checker;

core/filters.md

@@ -330,7 +330,7 @@ For instance, treat entries with a property value of `null` as the smallest, wit
 # app/config/api_filters.yml
 services:
     offer.order_filter:
-        parent: 'api_platform.doctrine.orm.date_filter'
+        parent: 'api_platform.doctrine.orm.order_filter'
         arguments: [ { validFrom: { nulls_comparison: 'nulls_smallest' } } ]
         tags: [ 'api_platform.filter' ]
 ```

core/getting-started.md

@@ -12,11 +12,11 @@ Alternatively, you can use [Composer](http://getcomposer.org) to install the sta
 
 `composer require api-platform/core`
 
-Then, update your `app/config/AppKernel.php` file:
+Then, update your `app/AppKernel.php` file:
 
 ```php
 <?php
-// app/config/AppKernel.php
+// app/AppKernel.php
 
 public function registerBundles()
 {
@@ -106,7 +106,7 @@ class Product // The class name will be used to name exposed resources
         $this->offers->add($offer);
     }
 
-    public function removeGreeting(Offer $offer): void
+    public function removeOffer(Offer $offer): void
     {
         $offer->product = null;
         $this->offers->removeElement($offer);

core/operation-path-naming.md

@@ -7,19 +7,19 @@ Pre-registered resolvers are available and can easily be overridden.
 
 There are two pre-registered operation path naming services:
 
-Service name                                      | Entity name  | Path result
---------------------------------------------------|--------------|----------------
-`api_platform.operation_path_resolver.underscore` | `MyResource` | `/my_resources`
-`api_platform.operation_path_resolver.dash`       | `MyResource` | `/my-resources`
+Service name                                          | Entity name  | Path result
+------------------------------------------------------|--------------|----------------
+`api_platform.path_segment_name_generator.underscore` | `MyResource` | `/my_resources`
+`api_platform.path_segment_name_generator.dash`       | `MyResource` | `/my-resources`
 
-The default resolver is `api_platform.operation_path_resolver.underscore`.
+The default resolver is `api_platform.path_segment_name_generator.underscore`.
 To change it to the dash resolver, add the following lines to `app/config/config.yml`:
 
 ```yaml
 # app/config/config.yml
 
 api_platform:
-    default_operation_path_resolver: 'api_platform.operation_path_resolver.dash'
+    path_segment_name_generator: api_platform.path_segment_name_generator.dash
 ```
 
 ## Create a Custom Operation Path Resolver
@@ -75,5 +75,5 @@ services:
 # app/config/config.yml
 
 api_platform:
-    default_operation_path_resolver: 'AppBundle\PathResolver\NoSeparatorsOperationPathResolver'
+    path_segment_name_generator: 'AppBundle\PathResolver\NoSeparatorsOperationPathResolver'
 ```

core/operations.md

@@ -287,6 +287,19 @@ class Question
 }
 ```
 
+Alternatively, you can use the YAML configuration format:
+
+```yaml
+AppBundle\Entity\Answer: ~
+AppBundle\Entity\Question:
+    properties:
+        answer:
+            subresource:
+                resourceClass: 'AppBundle\Entity\Answer'
+                collection: false
+```
+
+
 Note that all we had to do is to set up `@ApiSubresource` on the `Question::answer` relation. Because the `answer` is a to-one relation, we know that this subresource is an item. Therefore the response will look like this:
 
 ```json
@@ -360,6 +373,75 @@ Note that the operation name, here `api_questions_answer_get_subresource`, is th
 It'll be automatically set to `$resources_$subresource(s)_get_subresource`. To find the correct operation name you
 may use `bin/console debug:router`.
 
+### Control the Path of Subresources
+
+You can control the path of subresources with the `path` option of the `subresourceOperations` parameter:
+
+```php
+<?php
+// src/AppBundle/Entity/Question.php
+
+/**
+ * @ORM\Entity()
+ * @ApiResource(
+ *      subresourceOperations={
+ *          "answer_get_subresource"= {
+ *              "method"="GET",
+ *              "path"="/questions/{id}/all-answers",
+ *          },
+ *      },
+ * )
+ */
+class Question
+{
+}
+```
+
+### Control the Depth of Subresources
+
+You can control depth of subresources with the parameter `maxDepth`. For example, if `Answer` entity also have subresource such as `comments`and you don't want the route `api/questions/{id}/answers/{id}/comments` to be generated. You can do this by adding the parameter maxDepth in ApiSubresource annotation or yml/xml file configuration.
+
+```php
+<?php
+// src/AppBundle/Entity/Question.php
+
+use ApiPlatform\Core\Annotation\ApiProperty;
+use ApiPlatform\Core\Annotation\ApiResource;
+use ApiPlatform\Core\Annotation\ApiSubresource;
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * @ORM\Entity
+ * @ApiResource
+ */
+class Question
+{
+    /**
+     * @ORM\Column(type="integer")
+     * @ORM\Id
+     * @ORM\GeneratedValue(strategy="AUTO")
+     */
+    private $id;
+
+    /**
+     * @ORM\Column
+     */
+    public $content;
+
+    /**
+     * @ORM\OneToOne(targetEntity="Answer", inversedBy="question")
+     * @ORM\JoinColumn(referencedColumnName="id", unique=true)
+     * @ApiSubresource(maxDepth=1)
+     */
+    public $answer;
+
+    public function getId()
+    {
+        return $this->id;
+    }
+}
+```
+
 ## Creating Custom Operations and Controllers
 
 API Platform can leverage the Symfony routing system to register custom operation related to custom controllers. Such custom

core/serialization.md

@@ -417,19 +417,25 @@ services:
 
 ```php
 <?php
-// src/Appbundle/Serializer/ApiSerializer
+// src/Appbundle/Serializer/ApiNormalizer
 
 namespace AppBundle\Serializer;
 
-use ApiPlatform\Core\Serializer\AbstractItemNormalizer;
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+use Symfony\Component\Serializer\SerializerAwareInterface;
+use Symfony\Component\Serializer\SerializerInterface;
 
-final class ApiNormalizer extends AbstractItemNormalizer
+final class ApiNormalizer implements NormalizerInterface, DenormalizerInterface, SerializerAwareInterface
 {
     private $decorated;
 
     public function __construct(NormalizerInterface $decorated)
     {
+        if (!$decorated instanceof DenormalizerInterface) {
+            throw new \InvalidArgumentException(sprintf('The decorated normalizer must implement the %s.', DenormalizerInterface::class));
+        }
+
         $this->decorated = $decorated;
     }
 
@@ -457,6 +463,13 @@ final class ApiNormalizer extends AbstractItemNormalizer
     {
         return $this->decorated->denormalize($data, $class, $format, $context);
     }
+    
+    public function setSerializer(SerializerInterface $serializer)
+    {
+        if($this->decorated instanceof SerializerAwareInterface) {
+            $this->decorated->setSerializer($serializer);
+        }
+    }
 }
 ```