Merge 3.2

Author: soyuka

.php-cs-fixer.dist.php

@@ -18,6 +18,7 @@
         'tests/Fixtures/app/var',
         'docs/guides',
         'docs/var',
+        '**vendor**'
     ])
     ->notPath('src/Symfony/Bundle/DependencyInjection/Configuration.php')
     ->notPath('src/Annotation/ApiFilter.php') // temporary

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v3.2.2
+
+### Bug fixes
+
+* [3d0dfc148](https://github.com/api-platform/core/commit/3d0dfc148ec864364d1c36dfaa2690e1fc58dfc5) fix(symfony): swagger ui should use base url (#5918)
+* [4f51b5198](https://github.com/api-platform/core/commit/4f51b519853cf972070db79a8b82c824afa000fc) fix(symfony): use http exception headers (#5932)
+* [547c4e605](https://github.com/api-platform/core/commit/547c4e605c60c54642abc06c37462f5e47fbe25d) fix(graphql): item resolver inheritance error  (#5910)
+* [6b5df95ca](https://github.com/api-platform/core/commit/6b5df95caf2e3c6f807f2083ea3526fcd2ae473a) fix(doctrine): odm order filter should use a left join on nullable fields (#5911)
+* [ae090c7c4](https://github.com/api-platform/core/commit/ae090c7c4ec9619655ae95534b87a07aa7b2b061) fix(graphql): use normalization context to get item from IRI (#5915)
+* [b2d9ce40c](https://github.com/api-platform/core/commit/b2d9ce40cf27ee9743aafff4f163e195ae47b880) fix(serializer): pass $context to IriConverter (#5908)
+* [c2824c1d7](https://github.com/api-platform/core/commit/c2824c1d72f04a0d05b902b08a475a95db18e69f) fix(jsonschema): restore type factory usage (#5897)
+* [cd6f5834b](https://github.com/api-platform/core/commit/cd6f5834b7458798054fb4c7b3ea94f193246405) fix(serializer): use error normalizers (#5931)
+* [d9f77402d](https://github.com/api-platform/core/commit/d9f77402d55c40a867edf8fa15cee67c2801574f) fix(graphql): service missing in debug mode (#5930)
+
+Note:
+
+`extra_properties.skip_deprecated_exception_normalizers` is set to `false` so that decorating Error normalizers works. Set it to `true` to avoid deprecations and decorate the corresponding `ItemNormalizer` instead.
+
+## v3.2.1
+
+### Bug fixes
+
+* [05363d98f](https://github.com/api-platform/core/commit/05363d98f54babff49119a1fb55a17bb1550f21a) fix(symfony): force json format with GraphQL
+* [0c50d4ceb](https://github.com/api-platform/core/commit/0c50d4ceba9d83a2212771f21e2d1de4442c1456) fix(state): add link header processor without links (#5888)
+* [51b818304](https://github.com/api-platform/core/commit/51b818304874ec60ebab914455adc8f50402ca9d) fix: error traces without arguments (#5891)
+* [b7c094aca](https://github.com/api-platform/core/commit/b7c094acae3ac3271f42443ea2f62f22d019bea6) fix(metadata): interface breaking in 3.2 (#5883)
+* [dbd4f64de](https://github.com/api-platform/core/commit/dbd4f64debab876ab556ec87c8c973f0c38ada10) fix(graphql): docs should answer text/html
+
 ## v3.2.0
 
 ### Bug fixes
@@ -147,6 +175,19 @@ Notes:
 * [92a81f024](https://github.com/api-platform/core/commit/92a81f024541054b9322e7457b75c721261e14e0) feat(graphql): allow to disable the introspection query (#5711)
 * [d793ffb92](https://github.com/api-platform/core/commit/d793ffb9228a21655ee35f0b90a959f93281a4cf) feat: union/intersect types (#5470)
 
+## v3.1.22
+
+### Bug fixes
+
+* [157faafd5](https://github.com/api-platform/core/commit/157faafd54db75214b39fc8c7c6a97a171513c67) fix(state): wrong variable name
+* [b2d9ce40c](https://github.com/api-platform/core/commit/b2d9ce40cf27ee9743aafff4f163e195ae47b880) fix(serializer): pass $context to IriConverter (#5908)
+
+## v3.1.21
+
+### Bug fixes
+
+* [364732d83](https://github.com/api-platform/core/commit/364732d838f2fba05887fd24c75c4fb302c7af04) fix(serializer): missing parenthesis fixes #5773
+
 ## v3.1.20
 
 ### Bug fixes
@@ -158,7 +199,7 @@ Notes:
 ### Bug fixes
 
 * [6a62a53f8](https://github.com/api-platform/core/commit/6a62a53f854ec93947d1c4a5a32007df09e55d06) fix(hydra): add xxx[] hydra:search iexact
-* [7f0e00cd2](https://github.com/api-platform/core/commit/7f0e00cd2d838037f716e0b8588a6529ef9f158c) fix(mercure): custom topics on newly created entities causes error #5074 
+* [7f0e00cd2](https://github.com/api-platform/core/commit/7f0e00cd2d838037f716e0b8588a6529ef9f158c) fix(mercure): custom topics on newly created entities causes error #5074
 * [1fccb8413](https://github.com/api-platform/core/commit/1fccb8413a902a1011f049d0f8ddcd8d5456d335) fix(doctrine): add SearchFilter case-insensitive strategies constants
 
 ## v3.1.18
@@ -543,7 +584,7 @@ Breaking changes:
 * Metadata: `Patch` is added to the automatic CRUD
 * Symfony: generated route names and operation names changed, route naming can be changed directly within metadata
 * Doctrine: remove `@final` annotation from filters and mark them as `final`
-    
+
 ## v2.7.14
 
 ### Bug fixes

CONTRIBUTING.md

@@ -118,6 +118,8 @@ We strongly recommend the use of a scope on API Platform core.
 
 On `api-platform/core` there are two kinds of tests: unit (`phpunit` through `simple-phpunit`) and integration tests (`behat`).
 
+Note that we stopped using `prophesize` for new tests since 3.2, use `phpunit` stub system.
+
 Both `simple-phpunit` and `behat` are development dependencies and should be available in the `vendor` directory.
 
 #### PHPUnit and Coverage Generation

features/graphql/docs.feature

@@ -0,0 +1,10 @@
+Feature: Documentation support
+  In order to play with GraphQL
+  As a client software developer
+  I want to reach the GraphQL documentation
+
+    Scenario: Retrieve the OpenAPI documentation
+    Given I add "Accept" header equal to "text/html"
+    And I send a "GET" request to "/graphql"
+    Then the response status code should be 200
+    And the header "Content-Type" should be equal to "text/html; charset=utf-8"

features/main/exception_to_status.feature

@@ -38,3 +38,10 @@ Feature: Using exception_to_status config
     And I send a "DELETE" request to "/error_with_overriden_status/1"
     Then the response status code should be 403
     And the JSON node "status" should be equal to 403
+
+  @!mongodb
+  Scenario: Get HTTP Exception headers
+    When I add "Accept" header equal to "application/ld+json"
+    And I send a "GET" request to "/issue5924"
+    Then the response status code should be 429
+    Then the header "retry-after" should be equal to 32

phpstan.neon.dist

@@ -26,6 +26,7 @@ parameters:
 		- src/Symfony/Bundle/DependencyInjection/Configuration.php
 		# Templates for Maker
 		- src/Symfony/Maker/Resources/skeleton
+		- **vendor**
 	earlyTerminatingMethodCalls:
 		PHPUnit\Framework\Constraint\Constraint:
 			- fail

src/Api/FilterInterface.php

@@ -13,6 +13,44 @@
 
 namespace ApiPlatform\Api;
 
-interface FilterInterface extends \ApiPlatform\Metadata\FilterInterface
+/**
+ * Filters applicable on a resource.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+interface FilterInterface
 {
+    /**
+     * Gets the description of this filter for the given resource.
+     *
+     * Returns an array with the filter parameter names as keys and array with the following data as values:
+     *   - property: the property where the filter is applied
+     *   - type: the type of the filter
+     *   - required: if this filter is required
+     *   - strategy (optional): the used strategy
+     *   - is_collection (optional): if this filter is for collection
+     *   - swagger (optional): additional parameters for the path operation,
+     *     e.g. 'swagger' => [
+     *       'description' => 'My Description',
+     *       'name' => 'My Name',
+     *       'type' => 'integer',
+     *     ]
+     *   - openapi (optional): additional parameters for the path operation in the version 3 spec,
+     *     e.g. 'openapi' => [
+     *       'description' => 'My Description',
+     *       'name' => 'My Name',
+     *       'schema' => [
+     *          'type' => 'integer',
+     *       ]
+     *     ]
+     *   - schema (optional): schema definition,
+     *     e.g. 'schema' => [
+     *       'type' => 'string',
+     *       'enum' => ['value_1', 'value_2'],
+     *     ]
+     * The description can contain additional data specific to a filter.
+     *
+     * @see \ApiPlatform\OpenApi\Factory\OpenApiFactory::getFiltersParameters
+     */
+    public function getDescription(string $resourceClass): array;
 }

src/Api/FilterLocatorTrait.php

@@ -14,7 +14,7 @@
 namespace ApiPlatform\Api;
 
 use ApiPlatform\Exception\InvalidArgumentException;
-use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\FilterInterface as MetadataFilterInterface;
 use Psr\Container\ContainerInterface;
 
 /**
@@ -45,7 +45,7 @@ private function setFilterLocator(?ContainerInterface $filterLocator, bool $allo
     /**
      * Gets a filter with a backward compatibility.
      */
-    private function getFilter(string $filterId): ?FilterInterface
+    private function getFilter(string $filterId): null|FilterInterface|MetadataFilterInterface
     {
         if ($this->filterLocator && $this->filterLocator->has($filterId)) {
             return $this->filterLocator->get($filterId);

src/Api/IdentifiersExtractorInterface.php

@@ -13,15 +13,20 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\IdentifiersExtractorInterface::class);
+use ApiPlatform\Metadata\Exception\RuntimeException;
+use ApiPlatform\Metadata\Operation;
 
-class_alias(
-    \ApiPlatform\Metadata\IdentifiersExtractorInterface::class,
-    __NAMESPACE__.'\IdentifiersExtractorInterface'
-);
-
-if (false) { // @phpstan-ignore-line
-    interface IdentifiersExtractorInterface extends \ApiPlatform\Metadata\IdentifiersExtractorInterface
-    {
-    }
+/**
+ * Extracts identifiers for a given Resource according to the retrieved Metadata.
+ *
+ * @author Antoine Bluchet <[email protected]>
+ */
+interface IdentifiersExtractorInterface
+{
+    /**
+     * Finds identifiers from an Item (object).
+     *
+     * @throws RuntimeException
+     */
+    public function getIdentifiersFromItem(object $item, Operation $operation = null, array $context = []): array;
 }

src/Api/IriConverterInterface.php

@@ -13,15 +13,33 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\IriConverterInterface::class);
+use ApiPlatform\Metadata\Exception\InvalidArgumentException;
+use ApiPlatform\Metadata\Exception\ItemNotFoundException;
+use ApiPlatform\Metadata\Exception\RuntimeException;
+use ApiPlatform\Metadata\Operation;
 
-class_alias(
-    \ApiPlatform\Metadata\IriConverterInterface::class,
-    __NAMESPACE__.'\IriConverterInterface'
-);
+/**
+ * Converts item and resources to IRI and vice versa.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+interface IriConverterInterface
+{
+    /**
+     * Retrieves an item from its IRI.
+     *
+     * @throws InvalidArgumentException
+     * @throws ItemNotFoundException
+     */
+    public function getResourceFromIri(string $iri, array $context = [], Operation $operation = null): object;
 
-if (false) { // @phpstan-ignore-line
-    interface IriConverterInterface extends \ApiPlatform\Metadata\IriConverterInterface
-    {
-    }
+    /**
+     * Gets the IRI associated with the given item.
+     *
+     * @param object|class-string $resource
+     *
+     * @throws InvalidArgumentException
+     * @throws RuntimeException
+     */
+    public function getIriFromResource(object|string $resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, Operation $operation = null, array $context = []): ?string;
 }

src/Api/ResourceClassResolverInterface.php

@@ -13,10 +13,27 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\ResourceClassResolverInterface::class);
+use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 
-if (false) { // @phpstan-ignore-line
-    interface ResourceClassResolverInterface extends \ApiPlatform\Metadata\ResourceClassResolverInterface
-    {
-    }
+/**
+ * Guesses which resource is associated with a given object.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+interface ResourceClassResolverInterface
+{
+    /**
+     * Guesses the associated resource.
+     *
+     * @param string $resourceClass The expected resource class
+     * @param bool   $strict        If true, value must match the expected resource class
+     *
+     * @throws InvalidArgumentException
+     */
+    public function getResourceClass(mixed $value, string $resourceClass = null, bool $strict = false): string;
+
+    /**
+     * Is the given class a resource class?
+     */
+    public function isResourceClass(string $type): bool;
 }

src/Api/UriVariableTransformerInterface.php

@@ -13,6 +13,27 @@
 
 namespace ApiPlatform\Api;
 
-interface UriVariableTransformerInterface extends \ApiPlatform\Metadata\UriVariableTransformerInterface
+use ApiPlatform\Exception\InvalidUriVariableException;
+
+interface UriVariableTransformerInterface
 {
+    /**
+     * Transforms the value of a URI variable (identifier) to its type.
+     *
+     * @param mixed $value   The URI variable value to transform
+     * @param array $types   The guessed type behind the URI variable
+     * @param array $context Options available to the transformer
+     *
+     * @throws InvalidUriVariableException Occurs when the URI variable could not be transformed
+     */
+    public function transform(mixed $value, array $types, array $context = []);
+
+    /**
+     * Checks whether the value of a URI variable can be transformed to its type by this transformer.
+     *
+     * @param mixed $value   The URI variable value to transform
+     * @param array $types   The types to which the URI variable value should be transformed
+     * @param array $context Options available to the transformer
+     */
+    public function supportsTransformation(mixed $value, array $types, array $context = []): bool;
 }

src/Api/UriVariablesConverterInterface.php

@@ -13,15 +13,24 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\UriVariablesConverterInterface::class);
+use ApiPlatform\Metadata\Exception\InvalidIdentifierException;
 
-class_alias(
-    \ApiPlatform\Metadata\UriVariablesConverterInterface::class,
-    __NAMESPACE__.'\UriVariablesConverterInterface'
-);
-
-if (false) { // @phpstan-ignore-line
-    interface UriVariablesConverterInterface extends \ApiPlatform\Metadata\UriVariablesConverterInterface
-    {
-    }
+/**
+ * Identifier converter.
+ *
+ * @author Antoine Bluchet <[email protected]>
+ */
+interface UriVariablesConverterInterface
+{
+    /**
+     * Takes an array of strings representing URI variables (identifiers) and transform their values to the expected type.
+     *
+     * @param array  $data  URI variables to convert to PHP values
+     * @param string $class The class to which the URI variables belong to
+     *
+     * @throws InvalidIdentifierException
+     *
+     * @return array Array indexed by identifiers properties with their values denormalized
+     */
+    public function convert(array $data, string $class, array $context = []): array;
 }