Merge branch '2.4'

Author: dunglas

.editorconfig

@@ -0,0 +1,55 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+# Change these settings to your own preference
+indent_style = space
+indent_size = 4
+
+# We recommend you to keep these unchanged
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.json]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.neon]
+indent_style = tab
+indent_size = 4
+
+[*.xml]
+indent_style = space
+indent_size = 4
+
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false
+
+[.circleci/config.yml]
+indent_style = space
+indent_size = 2
+
+[.github/workflows/*.yml]
+indent_style = space
+indent_size = 2
+
+[.gitmodules]
+indent_style = tab
+
+[.proselintrc]
+indent_style = space
+indent_size = 2
+
+[.travis.yml]
+indent_style = space
+indent_size = 2

client-generator/nextjs.md

@@ -10,19 +10,15 @@ The Next.js Client Generator generates routes and components for Server Side Ren
 
 Create a [Next.js application with express server](https://github.com/zeit/next.js/tree/canary/examples/custom-server-express). The easiest way is to execute:  
 
-```bash
-$ npx create-next-app --example custom-server-express your-app-name
-# or
-$ yarn create next-app --example custom-server-express your-app-name
-```
+    $ npx create-next-app --example custom-server-express your-app-name
+    # or
+    $ yarn create next-app --example custom-server-express your-app-name
 
 ### Enabling Typescript
 
 Install typescript dependencies  
 
-```bash
-$ yarn add @types/next @zeit/next-typescript
-```
+    $ yarn add @types/next @zeit/next-typescript
 
 Enable Typescript in your Next.js configuration file (`next.config.js`):
 
@@ -72,33 +68,26 @@ Create a `tsconfig.json` file to store Typescript configuration:
 
 Install required dependencies:
 
-```bash
-$ yarn add lodash.get lodash.has @types/lodash isomorphic-unfetch
-```
+    $ yarn add lodash.get lodash.has @types/lodash isomorphic-unfetch
 
 ## Starting the Project
 
 You can launch the server with 
-```bash
-$ yarn dev
-```
+
+    $ yarn dev
 
 and access it through `http://localhost:3000`
 
 ## Generating Routes
 
-```bash
-$ npx @api-platform/client-generator https://demo.api-platform.com src/ --generator next --resource book
-# Replace the URL by the entrypoint of your Hydra-enabled API
-```
+    $ npx @api-platform/client-generator https://demo.api-platform.com src/ --generator next --resource book
+    # Replace the URL by the entrypoint of your Hydra-enabled API
 
 > Note: Omit the resource flag to generate files for all resource types exposed by the API.
 
 If your express server is compatible with the `custom-server-express` Next.js example, you can use the `server-path` flag to specify path to the server file. Routes will be added automatically to this file, otherwise, you will receive some hints on how to them to your own custom server.
 
-```bash
-$ npx @api-platform/client-generator https://demo.api-platform.com src/ --generator next --server-path ./server.js
-```
+    $ npx @api-platform/client-generator https://demo.api-platform.com src/ --generator next --server-path ./server.js
 
 Go to `https://localhost:3000/books/` to start using your app.
 That's it!

client-generator/react-native.md

@@ -9,26 +9,20 @@ To run the command line tool, we also recommend using [npx](https://www.npmjs.co
 
 Create a React Native application using [Expo CLI](https://docs.expo.io/versions/latest/workflow/expo-cli).
 
-```bash
-$ yarn global add expo-cli
-$ expo init my-app
-# When asked, choose to use the blank template
-$ cd my-app
-```
+    $ yarn global add expo-cli
+    $ expo init my-app
+    # When asked, choose to use the blank template
+    $ cd my-app
 
 Install the required dependencies:
 
-```bash
-$ yarn add redux react-redux redux-thunk redux-form react-native-elements react-native-router-flux react-native-vector-icons prop-types whatwg-url buffer react-native-event-source
-```
+    $ yarn add redux react-redux redux-thunk redux-form react-native-elements react-native-router-flux react-native-vector-icons prop-types whatwg-url buffer react-native-event-source
 
 ## Generating a Native App
 
 In the app directory, generate the files for the resource you want:
 
-```bash
-$ npx @api-platform/client-generator https://demo.api-platform.com . --generator react-native --resource book
-```
+    $ npx @api-platform/client-generator https://demo.api-platform.com . --generator react-native --resource book
 
 Replace the URL with the entrypoint of your Hydra-enabled API.
 Omit the resource flag to generate files for all resource types exposed by the API.
@@ -100,9 +94,7 @@ export default class App extends Component {
 
 The code is ready to be executed!
 
-```bash
-$ expo start
-```
+    $ expo start
 
 ## Screenshots in iOS Simulator
 

client-generator/react.md

@@ -24,45 +24,33 @@ To use this generator you need [Node.js](https://nodejs.org/) and [Yarn](https:/
 
 Bootstrap a React application:
 
-```bash
-$ npx create-react-app client
-$ cd client
-```
+    $ npx create-react-app client
+    $ cd client
 
 Install the required dependencies:
 
-```bash
-$ yarn add redux react-redux redux-thunk redux-form react-router-dom connected-react-router prop-types lodash
-```
+    $ yarn add redux react-redux redux-thunk redux-form react-router-dom connected-react-router prop-types lodash
 
 Optionally, install Bootstrap and Font Awesome to get an app that looks good:
 
-```bash
-$ yarn add bootstrap font-awesome
-```
+    $ yarn add bootstrap font-awesome
 
 Finally, start the integrated web server:
 
-```bash
-$ yarn start
-```
+    $ yarn start
 
 ## Generating a Progressive Web App
 
 If you use the API Platform distribution, generating all the code you need for a given resource is as simple as running the following command:
 
-```bash
-$ docker-compose exec client generate-api-platform-client --resource book
-```
+    $ docker-compose exec client generate-api-platform-client --resource book
 
 Omit the resource flag to generate files for all resource types exposed by the API.
 
 If you don't use the standalone installation, run the following command instead:
 
-```bash
-$ npx @api-platform/client-generator https://demo.api-platform.com src/ --resource book
-# Replace the URL by the entrypoint of your Hydra-enabled API
-```
+    $ npx @api-platform/client-generator https://demo.api-platform.com src/ --resource book
+    # Replace the URL by the entrypoint of your Hydra-enabled API
 
 The code has been generated, and is ready to be executed!
 Register the reducers and the routes in the `client/src/index.js` file:

client-generator/typescript.md

@@ -4,12 +4,10 @@ The TypeScript Generator allows you to create [TypeScript interfaces](https://ww
 
 To do so, run the client generator:
 
-```bash
-$ npx @api-platform/client-generator --generator typescript https://demo.api-platform.com src/ --resource foo
-# Replace the URL by the entrypoint of your Hydra-enabled API
-# "src/" represents where the interfaces will be generated
-# Omit the resource flag to generate files for all resource types exposed by the API
-```
+    $ npx @api-platform/client-generator --generator typescript https://demo.api-platform.com src/ --resource foo
+    # Replace the URL by the entrypoint of your Hydra-enabled API
+    # "src/" represents where the interfaces will be generated
+    # Omit the resource flag to generate files for all resource types exposed by the API
 
 This command parses the Hydra documentation and creates one `.ts` file for each API Resource you have defined in your application, in the `interfaces` subfolder.
 
@@ -19,9 +17,7 @@ NOTE: If you are not sure what the entrypoint is, see [Troubleshooting](troubles
 
 Assuming you have 2 resources in your application, `Foo` and `Bar`, when you run
 
-```bash
-npx @api-platform/client-generator --generator typescript https://demo.api-platform.com src/
-```
+    $ npx @api-platform/client-generator --generator typescript https://demo.api-platform.com src/
 
 you will obtain 2 `.ts` files arranged as following:
 

core/errors.md

@@ -75,7 +75,7 @@ api_platform:
     exception_to_status:
         # The 4 following handlers are registered by default, keep those lines to prevent unexpected side effects
         Symfony\Component\Serializer\Exception\ExceptionInterface: 400 # Use a raw status code (recommended)
-        ApiPlatform\Core\Exception\InvalidArgumentException: 'HTTP_BAD_REQUEST' # Or a `Symfony\Component\HttpFoundation\Response`'s constant
+        ApiPlatform\Core\Exception\InvalidArgumentException: !php/const Symfony\Component\HttpFoundation\Response::HTTP_BAD_REQUEST
         ApiPlatform\Core\Exception\FilterValidationException: 400
         Doctrine\ORM\OptimisticLockException: 409
 

core/file-upload.md

@@ -12,9 +12,7 @@ before proceeding. It will help you get a grasp on how the bundle works, and why
 
 Install the bundle with the help of Composer:
 
-```bash
-docker-compose exec php composer require vich/uploader-bundle
-```
+    $ docker-compose exec php composer require vich/uploader-bundle
 
 This will create a new configuration file that you will need to slightly change
 to make it look like this.

core/graphql.md

@@ -1,7 +1,5 @@
 # GraphQL Support
 
-## Overall View
-
 [GraphQL](http://graphql.org/) is a query language made to communicate with an API and therefore is an alternative to REST.
 
 It has some advantages compared to REST: it solves the over-fetching or under-fetching of data, is strongly typed, and is capable of retrieving multiple and nested data in one go, but it also comes with drawbacks. For example it creates overhead depending on the request.
@@ -14,9 +12,7 @@ Once enabled, you have nothing to do: your schema describing your API is automat
 
 To enable GraphQL and its IDE (GraphiQL and GraphQL Playground) in your API, simply require the [graphql-php](https://webonyx.github.io/graphql-php/) package using Composer and clear the cache one more time:
 
-```bash
-docker-compose exec php composer req webonyx/graphql-php && bin/console cache:clear
-```
+    $ docker-compose exec php composer req webonyx/graphql-php && bin/console cache:clear
 
 You can now use GraphQL at the endpoint: `https://localhost:8443/graphql`.
 

core/mercure.md

@@ -3,17 +3,18 @@
 API Platform can automatically send real time updates to the currently connected clients (webapps, mobile apps...) using [the Mercure protocol](https://mercure.rocks).
 
 > *Mercure* is a protocol allowing to push data updates to web browsers and other HTTP clients in a convenient, fast, reliable and battery-efficient way. It is especially useful to publish real-time updates of resources served through web APIs, to reactive web and mobile apps.
-> - https://mercure.rocks
+>
+> —https://mercure.rocks
 
 API Platform detects changes made to your Doctrine entities, and sends the updated resources to the Mercure hub.
 Then, the Mercure hub dispatches the updates to all connected clients using [Server-sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
 
 ![Mercure subscriptions](images/mercure-subscriptions.png)
 
-## Installing the Mercure Support
+## Installing Mercure Support
 
-The Mercure support is already installed, configured and enabled in [the official distribution](../distribution/index.md).
-If you use the distribution, you have nothing more to do, and you can jump to the next section.
+Mercure support is already installed, configured and enabled in [the API Platform distribution](../distribution/index.md).
+If you use the distribution, you have nothing more to do, and you can skip to the next section.
 
 If you have installed API Platform using another method (such as `composer require api`), you need to install a Mercure hub, and the [Symfony MercureBundle](https://github.com/symfony/mercure-bundle):
 

core/mongodb.md

@@ -16,38 +16,32 @@ the legacy [mongo](https://secure.php.net/manual/en/book.mongo.php) extension.
 
 ## Enabling MongoDB Support
 
-If the mongodb PHP extension is not installed yet, [install it beforehand](https://secure.php.net/manual/en/mongodb.installation.pecl.php).
+If the `mongodb` PHP extension is not installed yet, [install it beforehand](https://secure.php.net/manual/en/mongodb.installation.pecl.php).
 
-If you are using the [API Platform Distribution](../distribution/index.md), modify the Dockerfile to add the extension:
+If you are using the [API Platform Distribution](../distribution/index.md), modify the `Dockerfile` to add the extension:
 
 ```diff
- // api/Dockerfile
-
- ...
+# api/Dockerfile
  	pecl install \
  		apcu-${APCU_VERSION} \
 +		mongodb \
  	; \
- ...
+ 	pecl clear-cache; \
  	docker-php-ext-enable \
  		apcu \
- 		opcache \
 +		mongodb \
+ 		opcache \
  	; \
- ...
 ```
 
 Then rebuild the `php` image:
 
-```bash
-docker-compose build php
-```
+    $ docker-compose build php
 
 Add a MongoDB image to the docker-compose file:
 
 ```yaml
 # docker-compose.yml
-
 # ...
   db-mongodb:
       # In production, you may want to use a managed database service
@@ -69,17 +63,14 @@ Add a MongoDB image to the docker-compose file:
 Once the extension is installed, to enable the MongoDB support, require the [Doctrine MongoDB ODM bundle](https://github.com/doctrine/DoctrineMongoDBBundle)
 package using Composer:
 
-```bash
-docker-compose exec php composer req doctrine/mongodb-odm-bundle:^4.0.0@beta doctrine/mongodb-odm:^2.0.0@beta
-```
+    $ docker-compose exec php composer req doctrine/mongodb-odm-bundle:^4.0.0@beta doctrine/mongodb-odm:^2.0.0@beta
 
 Execute the contrib recipe to have it already configured.
 
 Change the MongoDB environment variables to match your Docker image:
 
 ```
 # api/.env
-
 MONGODB_URL=mongodb://api-platform:!ChangeMe!@db-mongodb
 MONGODB_DB=api
 ```
@@ -88,7 +79,6 @@ Change the configuration of API Platform to add the right mapping path:
 
 ```yaml
 # api/config/packages/api_platform.yaml
-
 api_platform:
     # ...