Merge branch 'api-platform:3.1' into 3.1

Author: mrossard

.github/workflows/cd.yml

@@ -28,24 +28,18 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-yarn-
 
-      - name: Install deps
-        run: yarn install
 
-      - name: Retrieve docs
-        run: bin/retrieve-documentation
-
-      - name: Build website
-        env:
-          GITHUB_KEY: ${{ secrets.CONTRIBUTORS_GITHUB_TOKEN }}
-          NODE_OPTIONS: --openssl-legacy-provider
-        run: yarn gatsby build
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.119.0'
+          extended: true
 
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Install php
+        uses: shivammathur/setup-php@v2
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./public
-          cname: api-platform.com
+          php-version: '8.2'
+          tools: phive
 
       - name: Auth gcloud
         uses: google-github-actions/auth@v1
@@ -54,6 +48,30 @@ jobs:
 
       - name: 'Set up Cloud SDK'
         uses: 'google-github-actions/setup-gcloud@v1'
-  
-      - name: Deploy on bucket
-        run: gsutil -m rsync -d -r ./public gs://api-platform-website-v3/
+
+      - name: Compute documentation
+        run: |
+          git clone https://github.com/api-platform/docs-website
+          cd docs-website
+          npm install
+          # fetches api-platform/docs
+          bash tools/get-docs.sh
+          # fetches api-platform/core for reference and guides
+          bash tools/get-core-docs.sh
+          # builds the config/_default/menu.toml according to the outline.yaml from api-platform/docs
+          node tools/menu.mjs
+          # build our tailwind theme
+          hugo --minify
+          gsutil -q -m rsync -d -r ./public gs://api-platform-website-v3/
+          # This need to move to website
+          # env:
+          #   GITHUB_KEY: ${{ secrets.CONTRIBUTORS_GITHUB_TOKEN }}
+          #   NODE_OPTIONS: --openssl-legacy-provider
+
+      # - name: Deploy
+      #   uses: peaceiris/actions-gh-pages@v3
+      #   with:
+      #     github_token: ${{ secrets.GITHUB_TOKEN }}
+      #     publish_dir: ./public
+      #     cname: api-platform.com
+

admin/authentication-support.md

@@ -79,9 +79,17 @@ const Admin = () => {
       </Head>
 
       <HydraAdmin dataProvider={dataProvider(setRedirectToLogin)} authProvider={authProvider} entrypoint={window.origin}>
-        <CustomRoutes>
-          {redirectToLogin ? <Route path="/" element={<RedirectToLogin />} /> : null}
-        </CustomRoutes>
+        {redirectToLogin ? (
+          <CustomRoutes>
+            <Route path="/" element={<RedirectToLogin />} />
+            <Route path="/:any" element={<RedirectToLogin />} />
+          </CustomRoutes>
+        ) : (
+          <>
+            <Resource name=".." list="..">
+            <Resource name=".." list="..">
+          </>
+        )}
       </HydraAdmin>
     </>
   );

admin/index.md

@@ -3,7 +3,7 @@
 ![Screencast](images/admin-demo.gif)
 
 API Platform Admin is a tool to automatically create a beautiful (Material Design) and fully-featured administration interface
-for any API supporting [the Hydra Core Vocabulary](http://www.hydra-cg.com/), exposing an [OpenAPI documentation](https://www.openapis.org/)
+for any API supporting [the Hydra Core Vocabulary](https://www.hydra-cg.com/), exposing an [OpenAPI documentation](https://www.openapis.org/)
 or other API specification formats supported by [`@api-platform/api-doc-parser`](https://github.com/api-platform/api-doc-parser).
 
 API Platform Admin is the perfect companion of APIs created

core/angularjs-integration.md

@@ -5,7 +5,7 @@ Warning: for a new project, you should consider using [the API Platform's Progre
 
 ## Restangular
 
-API Platform works fine with [AngularJS v1](http://angularjs.org). The popular [Restangular](https://github.com/mgonto/restangular)
+API Platform works fine with [AngularJS v1](https://angularjs.org/). The popular [Restangular](https://github.com/mgonto/restangular)
 REST client library for Angular can easily be configured to handle the API format.
 
 Here is a working Restangular config:

core/bootstrap.md

@@ -57,6 +57,7 @@ use ApiPlatform\JsonLd\Serializer\ObjectNormalizer as JsonLdObjectNormalizer;
 use ApiPlatform\JsonLd\ContextBuilder as JsonLdContextBuilder;
 use ApiPlatform\JsonSchema\SchemaFactory;
 use ApiPlatform\JsonSchema\TypeFactory;
+use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\CollectionOperationInterface;
 use ApiPlatform\Metadata\HttpOperation;
 use ApiPlatform\Metadata\Operation;
@@ -257,7 +258,7 @@ $providerCollection = new class implements ContainerInterface {
     }
 
     public function has($id): bool {
-        return isset($this->providers['id']);
+        return isset($this->providers[$id]);
     }
 };
 $stateProviders = new CallableProvider($providerCollection);
@@ -289,6 +290,12 @@ class Validator implements ValidatorInterface {
 $validator = new Validator(Validation::createValidator());
 $validateListener = new ValidateListener($validator, $resourceMetadataFactory);
 
+#[ApiResource(provider: \BookProvider::class)]
+class Book
+{
+    public int $id;
+}
+
 class BookProvider implements ProviderInterface
 {
     public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null

core/content-negotiation.md

@@ -22,9 +22,9 @@ Format                                                          | Format name  |
 ----------------------------------------------------------------|--------------|-------------------------------|----------------------------------------
 [JSON-LD](https://json-ld.org)                                  | `jsonld`     | `application/ld+json`         | yes
 [GraphQL](graphql.md)                                           | n/a          | n/a                           | yes
-[JSON:API](http://jsonapi.org/)                                 | `jsonapi`    | `application/vnd.api+json`    | yes
+[JSON:API](https://jsonapi.org/)                                | `jsonapi`    | `application/vnd.api+json`    | yes
 [HAL](https://stateless.group/hal_specification.html)           | `jsonhal`    | `application/hal+json`        | yes
-[YAML](http://yaml.org/)                                        | `yaml`       | `application/x-yaml`          | no
+[YAML](https://yaml.org/)                                       | `yaml`       | `application/x-yaml`          | no
 [CSV](https://tools.ietf.org/html/rfc4180)                      | `csv`        | `text/csv`                    | no
 [HTML](https://whatwg.org/) (API docs)                          | `html`       | `text/html`                   | no
 [XML](https://www.w3.org/XML/)                                  | `xml`        | `application/xml`, `text/xml` | no
@@ -119,9 +119,9 @@ Additionally the `csv` format is added with the MIME type `text/csv`.
 It is also important to notice that the usage of this attribute will override the formats defined in the configuration, therefore
 this configuration might disable the `json` or the `html` on this resource for example.
 
-You can specify different accepted formats at operation level too, it's especially convenient for to configure formats available for the `PATCH` method:
+You can specify different accepted formats at operation level too, it's especially convenient to configure formats available for the `PATCH` method:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -178,12 +178,12 @@ resources:
 </resources>
 ```
 
-[/codeSelector]
+</code-selector>
 
 ## Supporting Custom Formats
 
 The API Platform content negotiation system is extendable.
-You can add support for formats not available by default by creating custom normalizer and encoders.
+You can add support for formats not available by default by creating custom normalizers and encoders.
 Refer to the Symfony documentation to learn [how to create and register such classes](https://symfony.com/doc/current/serializer.html#adding-normalizers-and-encoders).
 
 Then, register the new format in the configuration:

core/controllers.md

@@ -4,7 +4,7 @@ Note: using custom controllers with API Platform is **discouraged**. Also, Graph
 [For most use cases, better extension points, working both with REST and GraphQL, are available](design.md).
 
 API Platform can leverage the Symfony routing system to register custom operations related to custom controllers. Such custom
-controllers can be any valid [Symfony controller](http://symfony.com/doc/current/book/controller.html), including standard
+controllers can be any valid [Symfony controller](https://symfony.com/doc/current/controller.html), including standard
 Symfony controllers extending the [`Symfony\Bundle\FrameworkBundle\Controller\AbstractController`](http://api.symfony.com/4.1/Symfony/Bundle/FrameworkBundle/Controller/AbstractController.html)
 helper class.
 
@@ -15,7 +15,7 @@ implements the [Action-Domain-Responder](https://github.com/pmjones/adr) pattern
 The distribution of API Platform also eases the implementation of the ADR pattern: it automatically registers action classes
 stored in `api/src/Controller` as autowired services.
 
-Thanks to the [autowiring](http://symfony.com/doc/current/components/dependency_injection/autowiring.html) feature of the
+Thanks to the [autowiring](https://symfony.com/doc/current/service_container/autowiring.html) feature of the
 Symfony Dependency Injection container, services required by an action can be type-hinted in its constructor, it will be
 automatically instantiated and injected, without having to declare it explicitly.
 
@@ -85,7 +85,7 @@ the client.
 
 The routing has not been configured yet because we will add it at the resource configuration level:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -143,7 +143,7 @@ resources:
 </resources>
 ```
 
-[/codeSelector]
+</code-selector>
 
 It is mandatory to set the `method`, `uriTemplate` and `controller` attributes. They allow API Platform to configure the routing path and
 the associated controller respectively.
@@ -158,7 +158,7 @@ To avoid that, API Platform provides the `ApiPlatform\Action\PlaceholderAction`
 
 You just need to set the `controller` attribute with this class. Here, the previous example updated:
 
-[codeSelector]
+<code-selector>
 
 ```php
 // api/src/Entity/Book.php
@@ -215,13 +215,13 @@ resources:
 </resources>
 ```
 
-[/codeSelector]
+</code-selector>
 
 ## Using Serialization Groups
 
 You may want different serialization groups for your custom operations. Just configure the proper `normalizationContext` and/or `denormalizationContext` in your operation:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -240,7 +240,7 @@ use Symfony\Component\Serializer\Annotation\Groups;
         name: 'publication', 
         uriTemplate: '/books/{id}/publication', 
         controller: CreateBookPublication::class, 
-        normalizationContext: ['groups' => 'publication']
+        normalizationContext: ['groups' => ['publication']],
     )
 ])]
 class Book
@@ -292,14 +292,14 @@ resources:
 </resources>
 ```
 
-[/codeSelector]
+</code-selector>
 
 ## Retrieving the Entity
 
 If you want to bypass the automatic retrieval of the entity in your custom operation, you can set `read: false` in the
 operation attribute:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -357,7 +357,7 @@ resources:
 </resources>
 ```
 
-[/codeSelector]
+</code-selector>
 
 This way, it will skip the `ReadListener`. You can do the same for some other built-in listeners. See [Built-in Event Listeners](events.md#built-in-event-listeners)
 for more information.
@@ -377,7 +377,7 @@ for `book_post_discontinuation` when neither `method` nor `routeName` attributes
 
 First, let's create your resource configuration:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -430,10 +430,10 @@ resources:
 </resources>
 ```
 
-[/codeSelector]
+</code-selector>
 
 API Platform will automatically map this `post_publication` operation to the route `book_post_publication`. Let's create a custom action
-and its related route using annotations:
+and its related route using attributes:
 
 ```php
 <?php

core/default-order.md

@@ -5,7 +5,7 @@ API Platform provides an easy way to override the default order of items in your
 By default, items in the collection are ordered in ascending (ASC) order by their resource identifier(s). If you want to
 customize this order, you must add an `order` attribute on your ApiResource annotation:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -35,12 +35,12 @@ App\Entity\Book:
         foo: ASC
 ```
 
-[/codeSelector]
+</code-selector>
 
 This `order` attribute is used as an array: the key defines the order field, the values defines the direction.
 If you only specify the key, `ASC` direction will be used as default. For example, to order by `foo` & `bar`:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -74,11 +74,11 @@ App\Entity\Book:
     order: ['foo', 'bar']
 ```
 
-[/codeSelector]
+</code-selector>
 
 It's also possible to configure the default order on an association property:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -107,11 +107,11 @@ App\Entity\Book:
     order: ['author.username']
 ```
 
-[/codeSelector]
+</code-selector>
 
 Another possibility is to apply the default order for a specific collection operation, which will override the global default order configuration.
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -155,4 +155,4 @@ App\Entity\Book:
             name: ASC
 ```
 
-[/codeSelector]
+</code-selector>

core/deprecations.md

@@ -9,7 +9,7 @@ It's a tedious task that should be avoided as much as possible.
 On the other hand, the evolution strategy (also known as versionless APIs) consists of deprecating the fields, resources
 types or operations that will be removed at some point.
 
-Most modern API formats including [JSON-LD / Hydra](content-negotiation.md), [GraphQL](graphql.md) and [OpenAPI](swagger.md)
+Most modern API formats including [JSON-LD / Hydra](content-negotiation.md), [GraphQL](graphql.md) and [OpenAPI](openapi.md)
 allow you to mark resources types, operations or fields as deprecated.
 
 ## Deprecating Resource Classes, Operations and Properties
@@ -67,7 +67,7 @@ class Parchment
 
 It's also possible to deprecate a single property:
 
-[codeSelector]
+<code-selector>
 
 ```php
 <?php
@@ -99,7 +99,7 @@ properties:
             deprecationReason: 'Use the rating property instead'
 ```
 
-[/codeSelector]
+</code-selector>
 
 * With JSON-lD / Hydra, [an `owl:deprecated` annotation property](https://www.w3.org/TR/owl2-syntax/#Annotation_Properties) will be added to the appropriate data structure
 * With Swagger / OpenAPI, [a `deprecated` property](https://swagger.io/docs/specification/2-0/paths-and-operations/) will be added

core/design.md

@@ -8,7 +8,7 @@ To do so, you have to write a plain old PHP object (POPO) representing the input
 that is [marked with the `#[ApiResource]` attribute](../distribution/index.md).
 This class **doesn't have** to be mapped with Doctrine ORM, or any other persistence system. It must be simple (it's usually
 just a data structure with no or minimal behaviors) and will be automatically converted to [Hydra](extending-jsonld-context.md),
-[OpenAPI](swagger.md) and [GraphQL](graphql.md) documentations or schemas by API Platform (there is a 1-1 mapping
+[OpenAPI](openapi.md) and [GraphQL](graphql.md) documentations or schemas by API Platform (there is a 1-1 mapping
 between this class and those docs).
 
 Then, it's up to the developer to feed API Platform with an hydrated instance of this API resource object by implementing