Fix/abstract normalizer constructor 2

.github/FUNDING.yml

@@ -0,0 +1 @@
+tidelift: "packagist/api-platform/core"

.github/workflows/ci.yml

@@ -596,7 +596,7 @@ jobs:
           - '7.4'
       fail-fast: false
     env:
-      SYMFONY_DEPRECATIONS_HELPER: max[total]=7
+      SYMFONY_DEPRECATIONS_HELPER: max[total]=8
     steps:
       - name: Checkout
         uses: actions/checkout@v2
@@ -836,3 +836,4 @@ jobs:
         run: tests/Fixtures/app/console cache:clear --ansi
       - name: Run Behat tests
         run: vendor/bin/behat --out=std --format=progress --profile=default --no-interaction
+

.gitignore

@@ -11,3 +11,4 @@
 /tests/Fixtures/app/var/
 /tests/Fixtures/app/public/bundles/
 /vendor/
+/Dockerfile

.php_cs.dist

@@ -29,6 +29,7 @@ return PhpCsFixer\Config::create()
         '@PHPUnit60Migration:risky' => true,
         '@Symfony' => true,
         '@Symfony:risky' => true,
+        'single_line_comment_style' => false, // Temporary fix for compatibility with PHP 8 attributes, see https://github.com/FriendsOfPHP/PHP-CS-Fixer/pull/5284
         'align_multiline_comment' => [
             'comment_type' => 'phpdocs_like',
         ],

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2.6.0
+
+* Display the API Platform's version in the debug-bar
+* MongoDB: Possibility to add execute options (aggregate command fields) for a resource, like `allowDiskUse` (#3144)
+* MongoDB: Mercure support (#3290)
+* GraphQL: Subscription support with Mercure (#3321)
+* GraphQL: Allow to format GraphQL errors based on exceptions (#3063)
+* GraphQL: Add page-based pagination (#3175, #3517)
+* GraphQL: Errors thrown from the GraphQL library can now be handled (#3632)
+* GraphQL: Possibility to add a custom description for queries, mutations and subscriptions (#3477, #3514)
+* GraphQL: Support for field name conversion (serialized name) (#3455, #3516)
+* GraphQL: **BC** `operation` is now `operationName` to follow the standard (#3568)
+* GraphQL: **BC** New syntax for the filters' arguments to preserve the order: `order: [{foo: 'asc'}, {bar: 'desc'}]` (#3468)
+* OpenAPI: Add PHP default values to the documentation (#2386)
+* Deprecate using a validation groups generator service not implementing `ApiPlatform\Core\Bridge\Symfony\Validator\ValidationGroupsGeneratorInterface` (#3346)
+* Subresources: subresource resourceClass can now be defined as a container parameter in XML and Yaml definitions
+* IriConverter: Fix IRI url double encoding - may cause breaking change as some characters no longer encoded in output (#3552)
+* OpenAPI: **BC** Replace all characters other than `[a-zA-Z0-9\.\-_]` to `.` in definition names to be compliant with OpenAPI 3.0 (#3669)
+* Add stateless ApiResource attribute
+
 ## 2.5.8
 
 For compatibility reasons with Symfony 5.2 and PHP 8, we do not test these legacy packages nor their integration anymore:
@@ -130,7 +150,7 @@ For compatibility reasons with Symfony 5.2 and PHP 8, we do not test these legac
 
 * Allow to not declare GET item operation
 * Add support for the Accept-Patch header
-* Make the `maximum_items_per_page` attribute consistent with other attributes controlling pagination 
+* Make the `maximum_items_per_page` attribute consistent with other attributes controlling pagination
 * Allow to use a string instead of an array for serializer groups
 * Test: Add a helper method to find the IRI of a resource
 * Test: Add assertions for testing response against JSON Schema from API resource

CONTRIBUTING.md

@@ -18,11 +18,6 @@ Then, if it appears that it's a real bug, you may report it using GitHub by foll
 
 > _NOTE:_ Don't hesitate giving as much information as you can (OS, PHP version extensions...)
 
-### Security Issues
-
-If you find a security issue, send a mail to Kévin Dunglas <dunglas@gmail.com>. **Please do not report security problems
-publicly**. We will disclose details of the issue and credit you after having released a new version including a fix.
-
 ## Pull Requests
 
 ### Writing a Pull Request
@@ -50,7 +45,7 @@ Alternatively, you can also work with the test application we provide:
 ### Matching Coding Standards
 
 The API Platform project follows [Symfony coding standards](https://symfony.com/doc/current/contributing/code/standards.html).
-But don't worry, you can fix CS issues automatically using the [PHP CS Fixer](http://cs.sensiolabs.org/) tool:
+But don't worry, you can fix CS issues automatically using the [PHP CS Fixer](https://cs.sensiolabs.org/) tool:
 
     php-cs-fixer.phar fix
 
@@ -68,8 +63,6 @@ When you send a PR, just make sure that:
 that you did not make in your PR, you're doing it wrong.
 * Also don't forget to add a comment when you update a PR with a ping to [the maintainers](https://github.com/orgs/api-platform/people), so he/she will get a notification.
 
-All Pull Requests must include [this header](.github/PULL_REQUEST_TEMPLATE.md).
-
 ### Tests
 
 On `api-platform/core` there are two kinds of tests: unit (`phpunit` through `simple-phpunit`) and integration tests (`behat`).

behat.yml.dist

@@ -132,3 +132,4 @@ elasticsearch-coverage:
         - 'ApiPlatform\Core\Tests\Behat\CoverageContext'
         - 'Behat\MinkExtension\Context\MinkContext'
         - 'behatch:context:rest'
+

composer.json

@@ -93,6 +93,7 @@
         "doctrine/mongodb-odm-bundle": "To support MongoDB. Only versions 4.0 and later are supported.",
         "elasticsearch/elasticsearch": "To support Elasticsearch.",
         "guzzlehttp/guzzle": "To use the HTTP cache invalidation system.",
+        "ocramius/package-versions": "To display the API Platform's version in the debug bar.",
         "phpdocumentor/reflection-docblock": "To support extracting metadata from PHPDoc.",
         "psr/cache-implementation": "To use metadata caching.",
         "ramsey/uuid": "To support Ramsey's UUID identifiers.",
@@ -101,6 +102,7 @@
         "symfony/expression-language": "To use authorization features.",
         "symfony/security": "To use authorization features.",
         "symfony/twig-bundle": "To use the Swagger UI integration.",
+        "symfony/uid": "To support Symfony UUID/ULID identifiers.",
         "symfony/web-profiler-bundle": "To use the data collector.",
         "webonyx/graphql-php": "To support GraphQL."
     },
@@ -122,7 +124,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.5.x-dev"
+            "dev-master": "2.6.x-dev"
         },
         "symfony": {
             "require": "^3.4 || ^4.4 || ^5.1"

docs/adr/0000-subresources-definition.md

@@ -0,0 +1,157 @@
+# Subresource Definition
+
+* Status: proposed
+* Deciders: @dunglas, @vincentchalamon, @soyuka, @GregoireHebert, @Deuchnord
+
+## Context and Problem Statement
+
+Subresources introduced in 2017 ([#904][pull/904]) the `ApiSubresource` annotation. This definition came along with its own set of issues ([#2706][issue/2706]) and needs a refreshment. On top of that, write support on subresources is a wanted feature and it is hard to implement currently ([#2598][pull/2598]) (See [ADR-0001-subresource-write-support](./0001-subresource-write-support.md)). How can we revamp the Subresource definition to improve the developer experience and reduce the complexity?
+
+## Considered Options
+
+* Fix the current `ApiSubresource` annotation
+* Use multiple `ApiResource` to declare subresources and deprecate `ApiSubresource`
+* Deprecate subresources
+
+## Decision Outcome
+
+We choose to use multiple `ApiResource` annotations to declare subresources on a given Model class: 
+
+* Subresource declaration is an important feature and removing it would harm the software. 
+* The `ApiSubresource` annotation is declared on a Model's properties, which was identified as the root of several issues. For example, finding what class it is defined on ([#3458][issue/3458]). Having multiple `ApiResource` would improve a lot the declaration of our internal metadata and would cause less confusion for developers. 
+* The `path` of these multiple `ApiResource` needs to be explicitly described. 
+* An `ApiResource` is always defined on the Resource it represents: `/companies/1/users` outputs Users and should be defined on the `User` model.
+* PropertyInfo and Doctrine metadata can be used to define how is the Resource identified according to the given path.
+
+### Examples
+
+Get Users belonging to the company on (`/companies/1/users`);
+
+```php
+/**
+ * @ApiResource(path="/users")
+ * @ApiResource(path="/companies/{companyId}/users")
+ */
+class User {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Company[] */
+  public array $companies = [];
+}
+```
+
+With explicit identifiers, the tuple is explained in [ADR-0002-identifiers](./0002-identifiers) `{parameterName: {Class, property}}`:
+
+```php
+/**
+ * @ApiResource(path="/users", identifiers={"id": {User::class, "id"}})
+ * @ApiResource(path="/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "id": {User::class, "id"}})
+ */
+class User {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Company[] */
+  public array $companies = [];
+}
+```
+
+Two-level subresource to get the Users belonging to the Company #1 located in France `/countries/fr/companies/1/users`: 
+
+```php
+/**
+ * @ApiResource(path="/users")
+ * @ApiResource(path="/countries/{countryId}/companies/{companyId}/users")
+ */
+class User {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Company[] */
+  public array $companies = [];
+}
+
+class Company {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Country[] **/
+  public array $countries = [];
+}
+
+class Country {
+  /** @ApiProperty(identifier=true) */
+  public string $shortName;
+}
+```
+
+With explicit identifiers:
+
+```php
+/**
+ * @ApiResource(path="/users", identifiers={"id": {User::class, "id"}})
+ * @ApiResource(path="/countries/{countryId}/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "countryId": {Country::class, "shortName"}, "id": {User::class, "id"}})
+ */
+class User {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Company[] */
+  public array $companies = [];
+}
+
+class Company {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Country[] **/
+  public array $countries = [];
+}
+
+class Country {
+  /** @ApiProperty(identifier=true) */
+  public string $shortName;
+}
+```
+
+Get the company employees or administrators `/companies/1/administrators`:
+
+```php
+/**
+ * @ApiResource(path="/users")
+ * @ApiResource(path="/companies/{companyId}/administrators")
+ * @ApiResource(path="/companies/{companyId}/employees")
+ */
+class User {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var Company[] */
+  public array $companies = [];
+}
+
+class Company {
+  /** @ApiProperty(identifier=true) */
+  public int $id;
+
+  /** @var User[] **/
+  public array $employees;
+
+  /** @var User[] **/
+  public array $administrators;
+}
+```
+
+This example will require a custom DataProvider as the discriminator needs to be explicit.
+
+## Links
+
+* [Subresource refactor][pull/3689]
+
+
+[pull/904]: https://github.com/api-platform/core/pull/904  "Subresource feature"
+[issue/2706]: https://github.com/api-platform/core/issues/2706 "Subresource RFC"
+[pull/2598]: https://github.com/api-platform/core/pull/2598 "Subresource write support"
+[issue/3458]: https://github.com/api-platform/core/pull/3458 "Subresource poor DX"
+[pull/3689]: https://github.com/api-platform/core/pull/3689 "Revamp subresource"