Skip to content

Commit abc94b9

Browse files
dunglassoyukaalanpoulain
authored
Docs for API Platform 2.6 (#1255)
* Docs for API Platform 2.6 * Update core/data-persisters.md Co-authored-by: Antoine Bluchet <[email protected]> * Update distribution/index.md Co-authored-by: Antoine Bluchet <[email protected]> * Update distribution/index.md Co-authored-by: Antoine Bluchet <[email protected]> * Update index.md * Update core/content-negotiation.md Co-authored-by: Alan Poulain <[email protected]> * Update core/serialization.md Co-authored-by: Alan Poulain <[email protected]> * Update distribution/index.md Co-authored-by: Alan Poulain <[email protected]> * Update distribution/index.md Co-authored-by: Alan Poulain <[email protected]> * Update distribution/index.md Co-authored-by: Alan Poulain <[email protected]> * minor tweak Co-authored-by: Antoine Bluchet <[email protected]> Co-authored-by: Alan Poulain <[email protected]>
1 parent c60a968 commit abc94b9

17 files changed

+429
-404
lines changed

admin/handling-relations.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,9 +157,9 @@ use ApiPlatform\Core\Annotation\ApiResource;
157157
use Doctrine\ORM\Mapping as ORM;
158158

159159
/**
160-
* @ApiResource
161160
* @ORM\Entity
162161
*/
162+
#[ApiResource]
163163
class Review
164164
{
165165
/**
@@ -189,9 +189,9 @@ use Doctrine\Common\Collections\ArrayCollection;
189189
use Doctrine\ORM\Mapping as ORM;
190190

191191
/**
192-
* @ApiResource
193192
* @ORM\Entity
194193
*/
194+
#[ApiResource]
195195
class Book
196196
{
197197
/**

admin/performance.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,9 @@ use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter;
2626
use Doctrine\ORM\Mapping as ORM;
2727

2828
/**
29-
* @ApiResource
3029
* @ORM\Entity
3130
*/
31+
#[ApiResource]
3232
class Author
3333
{
3434
/**

client-generator/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ Client Generator is the fastest way to scaffold fully featured webapps and nativ
88

99
It is able to generate apps using the following frontend stacks:
1010

11-
* [React with Redux](react.md)
12-
* [React Native](react-native.md)
1311
* [Next.js](nextjs.md)
1412
* [Nuxt.js](nuxtjs.md)
15-
* [Vue.js](vuejs.md)
1613
* [Quasar Framework](quasar.md)
1714
* [Vuetify](vuetify.md)
15+
* [React with Redux](react.md)
16+
* [React Native](react-native.md)
17+
* [Vue.js](vuejs.md)
1818

1919
Client Generator works especially well with APIs built with the [API Platform](https://api-platform.com) framework.
2020

core/bootstrap.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Bootstraping the core library
1+
# Bootstraping the core library
22

33
You may want to run a minimal version of API Platform. This one file runs API Platform (without graphql, doctrine and mongodb).
44
It requires the following composer packages:

core/content-negotiation.md

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -104,9 +104,9 @@ The `format` attribute can be used as a shortcut, it sets both the `input_format
104104
105105
namespace App\Entity;
106106
107-
/**
108-
* @ApiResource(formats={"xml", "jsonld", "csv"={"text/csv"}})
109-
*/
107+
use ApiPlatform\Core\Annotation\ApiResource;
108+
109+
#[ApiResource(formats: ['xml', 'jsonld', 'csv' => ['text/csv']])]
110110
class Book
111111
{
112112
// ...
@@ -128,16 +128,18 @@ You can specify different accepted formats at operation level too, it's especial
128128
129129
namespace App\Entity;
130130
131-
/**
132-
* @ApiResource(
133-
* formats={"jsonld", "csv"={"text/csv"}},
134-
* itemOperations={
135-
* "patch"={
136-
* "input_formats"={"json"={"application/merge-patch+json"}}
137-
* }
138-
* }
139-
* )
140-
*/
131+
use ApiPlatform\Core\Annotation\ApiResource;
132+
133+
#[ApiResource(
134+
formats: ['jsonld', 'csv' => ['text/csv']],
135+
itemOperations: [
136+
'patch' => [
137+
'input_formats' => [
138+
'json' => ['application/merge-patch+json'],
139+
],
140+
],
141+
],
142+
)]
141143
class Book
142144
{
143145
// ...

core/controllers.md

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -87,16 +87,14 @@ The routing has not been configured yet because we will add it at the resource c
8787
use ApiPlatform\Core\Annotation\ApiResource;
8888
use App\Controller\CreateBookPublication;
8989

90-
/**
91-
* @ApiResource(itemOperations={
92-
* "get",
93-
* "post_publication"={
94-
* "method"="POST",
95-
* "path"="/books/{id}/publication",
96-
* "controller"=CreateBookPublication::class,
97-
* }
98-
* })
99-
*/
90+
#[ApiResource(itemOperations: [
91+
'get',
92+
'post_publication' => [
93+
'method' => 'POST',
94+
'path' => '/books/{id}/publication',
95+
'controller" => CreateBookPublication::class,
96+
],
97+
])
10098
class Book
10199
{
102100
//...

core/data-persisters.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
To mutate the application states during `POST`, `PUT`, `PATCH` or `DELETE` [operations](operations.md), API Platform uses
44
classes called **data persisters**. Data persisters receive an instance of the class marked as an API resource (usually using
5-
the `@ApiResource` annotation). This instance contains data submitted by the client during [the deserialization
5+
the `#[ApiResource]` attribute). This instance contains data submitted by the client during [the deserialization
66
process](serialization.md).
77

88
<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform-security/encode-user-password?cid=apip"><img src="../distribution/images/symfonycasts-player.png" alt="Data Persister screencast"><br>Watch the Data Persister screencast</a></p>

core/design.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ API framework. However, the "design-first" methodology is strongly recommended:
55
API endpoints.
66

77
To do so, you have to write a plain old PHP object (POPO) representing the input and output of your endpoint. This is the class
8-
that is [marked with the `@ApiResource` annotation](../distribution/index.md).
8+
that is [marked with the `#[ApiResource]` attribute](../distribution/index.md).
99
This class **doesn't have** to be mapped with Doctrine ORM, or any other persistence system. It must be simple (it's usually
1010
just a data structure with no or minimal behaviors) and will be automatically converted to [Hydra](extending-jsonld-context.md),
1111
[OpenAPI](swagger.md) and [GraphQL](graphql.md) documentations or schemas by API Platform (there is a 1-1 mapping
@@ -19,8 +19,8 @@ When updating a state (`POST`, `PUT`, `PATCH`, `DELETE` HTTP methods), it's up t
1919
data provided by API Platform's resource object [hydrated by the serializer](serialization.md).
2020
To do so, there is another interface to implement: [`DataPersisterInterface`](data-persisters.md).
2121

22-
This class will read the API resource object (the one marked with `@ApiResource`) and:
23-
22+
This class will read the API resource object (the one marked with `#[ApiResource]`) and:
23+
2424
* persist it directly in the database;
2525
* or hydrate a DTO then trigger a command;
2626
* or populate an event store;
@@ -29,10 +29,10 @@ This class will read the API resource object (the one marked with `@ApiResource`
2929
The logic of data persisters is the responsibility of application developers, and is **out of the API Platform's scope**.
3030

3131
For [Rapid Application Development](https://en.wikipedia.org/wiki/Rapid_application_development), convenience and prototyping,
32-
**if and only if the class marked with `@ApiResource` is also a Doctrine entity**, the developer can use the Doctrine
32+
**if and only if the class marked with `#[ApiResource]` is also a Doctrine entity**, the developer can use the Doctrine
3333
ORM's data provider and persister implementations shipped with API Platform.
3434

35-
In this case, the public (`@ApiResource`) and internal (Doctrine entity) data models are shared. Then, API Platform will
35+
In this case, the public (`#[ApiResource]`) and internal (Doctrine entity) data models are shared. Then, API Platform will
3636
be able to query, filter, paginate and persist data automatically.
3737
This approach is super-convenient and efficient, but is probably **not a good idea** for non-[CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
3838
and/or large systems.
@@ -47,6 +47,6 @@ approach is:
4747

4848
* to persist data in an event store using a Messenger handler or a custom [data persister](data-persisters.md)
4949
* to create projections in standard RDBMS (PostgreSQL, MariaDB...) tables or views
50-
* to map those projections with read-only Doctrine entity classes **and** to mark those classes with `@ApiResource`
50+
* to map those projections with read-only Doctrine entity classes **and** to mark those classes with `#[ApiResource]`
5151

5252
You can then benefit from the built-in Doctrine filters, sorting, pagination, auto-joins and all of [the extension points](extending.md) provided by API Platform.

core/elasticsearch.md

Lines changed: 17 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Be careful, API Platform only supports Elasticsearch >= 6.5.0.
1515
To enable the reading support for Elasticsearch, simply require the Elasticsearch-PHP package using Composer:
1616

1717
$ composer require elasticsearch/elasticsearch:^6.0
18-
18+
1919
Then, enable it inside the API Platform configuration:
2020

2121
```yaml
@@ -39,6 +39,7 @@ api_platform:
3939
## Creating Models
4040

4141
API Platform follows the best practices of Elasticsearch:
42+
4243
* 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
4344
index](https://www.elastic.co/guide/en/elasticsearch/reference/current/removal-of-types.html);
4445
* index name should be the short resource name in lower snake case;
@@ -145,42 +146,24 @@ namespace App\Model;
145146
use ApiPlatform\Core\Annotation\ApiProperty;
146147
use ApiPlatform\Core\Annotation\ApiResource;
147148

148-
/**
149-
* @ApiResource
150-
*/
149+
#[ApiResource]
151150
class User
152151
{
153-
/**
154-
* @ApiProperty(identifier=true)
155-
*
156-
* @var string
157-
*/
158-
public $id;
152+
#[ApiProperty(identifier: true)]
153+
public string $id = '';
159154

160-
/**
161-
* @var string
162-
*/
163-
public $gender;
155+
public string $gender;
164156

165-
/**
166-
* @var int
167-
*/
168-
public $age;
157+
public int $age;
169158

170-
/**
171-
* @var string
172-
*/
173-
public $firstName;
159+
public string $firstName;
174160

175-
/**
176-
* @var string
177-
*/
178-
public $lastName;
161+
public string $lastName;
179162

180163
/**
181164
* @var Tweet[]
182165
*/
183-
public $tweets = [];
166+
public iterable $tweets = [];
184167
}
185168
```
186169

@@ -193,36 +176,21 @@ namespace App\Model;
193176
use ApiPlatform\Core\Annotation\ApiProperty;
194177
use ApiPlatform\Core\Annotation\ApiResource;
195178

196-
/**
197-
* @ApiResource
198-
*/
179+
#[ApiResource]
199180
class Tweet
200181
{
201-
/**
202-
* @ApiProperty(identifier=true)
203-
*
204-
* @var string
205-
*/
206-
public $id;
182+
#[ApiProperty(identifier: true)]
183+
public string $id = '';
207184

208-
/**
209-
* @var User
210-
*/
211-
public $author;
185+
public User $author;
212186

213-
/**
214-
* @var \DateTimeInterface
215-
*/
216-
public $date;
187+
public \DateTimeInterface $date;
217188

218-
/**
219-
* @var string
220-
*/
221-
public $message;
189+
public string $message;
222190
}
223191
```
224192

225-
API Platform will automatically disable write operations and snake case document fields will automatically be converted to
193+
API Platform will automatically disable write operations and snake case document fields will automatically be converted to
226194
camel case object properties during serialization.
227195

228196
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),

core/filters.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -786,14 +786,18 @@ class Book
786786
```
787787

788788
Three arguments are available to configure the filter:
789-
- `parameterName` is the query parameter name (default `groups`)
790-
- `overrideDefaultGroups` allows to override the default serialization groups (default `false`)
791-
- `whitelist` groups whitelist to avoid uncontrolled data exposure (default `null` to allow all groups)
789+
790+
* `parameterName` is the query parameter name (default `groups`)
791+
* `overrideDefaultGroups` allows to override the default serialization groups (default `false`)
792+
* `whitelist` groups whitelist to avoid uncontrolled data exposure (default `null` to allow all groups)
792793

793794
Given that the collection endpoint is `/books`, you can filter by serialization groups with the following query: `/books?groups[]=read&groups[]=write`.
794795

795796
### Property filter
796797

798+
**Note:** We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this filter.
799+
Vulcain is faster, allows a better hit rate, and is supported out of the box in the API Platform distribution.
800+
797801
The property filter adds the possibility to select the properties to serialize (sparse fieldsets).
798802

799803
Syntax: `?properties[]=<property>&properties[<relation>][]=<property>`
@@ -823,9 +827,10 @@ class Book
823827
```
824828

825829
Three arguments are available to configure the filter:
826-
- `parameterName` is the query parameter name (default `properties`)
827-
- `overrideDefaultProperties` allows to override the default serialization properties (default `false`)
828-
- `whitelist` properties whitelist to avoid uncontrolled data exposure (default `null` to allow all properties)
830+
831+
* `parameterName` is the query parameter name (default `properties`)
832+
* `overrideDefaultProperties` allows to override the default serialization properties (default `false`)
833+
* `whitelist` properties whitelist to avoid uncontrolled data exposure (default `null` to allow all properties)
829834

830835
Given that the collection endpoint is `/books`, you can filter the serialization properties with the following query: `/books?properties[]=title&properties[]=author`.
831836
If you want to include some properties of the nested "author" document, use: `/books?properties[]=title&properties[author][]=name`.

core/fosuser-bundle.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# FOSUserBundle Integration
22

3-
API Platform Core is shipped with a bridge for [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle).
4-
If the FOSUser bundle is enabled, this bridge will use its `UserManager` to create, update and delete user resources.
3+
**Deprecated: this integration is deprecated and will be removed in API Platform 3**
54

6-
Note: FOSUserBundle is not well suited for APIs. We strongly encourage you to use the [Doctrine user provider](https://symfony.com/doc/current/security/user_provider.html#entity-user-provider)
5+
FOSUserBundle is not well suited for APIs. We strongly encourage you to use the [Doctrine user provider](https://symfony.com/doc/current/security/user_provider.html#entity-user-provider)
76
shipped with Symfony or to [create a custom user provider](https://symfony.com/doc/current/security/user_provider.html#creating-a-custom-user-provider)
87
instead of using this bundle.
98

9+
API Platform Core is shipped with a bridge for [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle).
10+
If the FOSUser bundle is enabled, this bridge will use its `UserManager` to create, update and delete user resources.
11+
1012
<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/user-entity?cid=apip"><img src="../distribution/images/symfonycasts-player.png" alt="User Entity screencast"><br>Watch the User Entity screencast</a></p>
1113

1214
## Installing the Bundle

core/push-relations.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
77
API Platform leverages this capability by pushing relations of a resource to clients.
88

9+
**Note:** We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this feature.
10+
Vulcain is faster, cleaner, more flexible, and is supported out of the box in the API Platform distribution.
11+
912
```php
1013
<?php
1114

core/serialization.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,10 @@ Refer to the [operations](operations.md) documentation to learn more.
214214
By default, the serializer provided with API Platform represents relations between objects using [dereferenceable IRIs](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier).
215215
They allow you to retrieve details for related objects by issuing extra HTTP requests. However, for performance reasons, it is sometimes preferable to avoid forcing the client to issue extra HTTP requests.
216216

217+
**Note:** We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this feature. Vulcain allows creating faster (better hit rate) and better designed APIs than relying on compound documents, and is supported out of the box in the API Platform distribution.
218+
217219
### Normalization
220+
218221
In the following JSON document, the relation from a book to an author is by default represented by an URI:
219222

220223
```json

deployment/docker-compose.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Deploying with Docker Compose
1+
# Deploying with Docker Compose
22

33
While [Docker Compose](https://docs.docker.com/compose/) is mainly known and used in a development environment, it [can
44
actually be used in production too](https://docs.docker.com/compose/production/). This is especially suitable for prototyping

0 commit comments

Comments
 (0)