diff --git a/core/filters.md b/core/filters.md index 07ff9d5fc99..4ee1cfcb5a7 100644 --- a/core/filters.md +++ b/core/filters.md @@ -894,8 +894,16 @@ entities: ### Creating a Custom Parameter Provider You can create your own providers to implement any custom logic. A provider must implement -`ParameterProviderInterface`. The `provide` method can modify the parameter's value or even return a -modified `Operation` to alter the request handling flow. +`ParameterProviderInterface`. Parameters are immutable and shared across requests, so the `provide` +method never modifies the parameter it receives. Since API Platform 5.1, it returns +`Operation|Parameter|null`: + +- a new `Parameter` (`return $parameter->withValue($value);`) to change only the parameter's value, +- a modified `Operation` (for example holding a replaced parameter) to alter the request handling + flow, +- `null` to leave everything unchanged. + +Calling `Parameter::setValue()` is deprecated and will be removed in 6.0. For instance, a provider could add serialization groups to the normalization context based on a query parameter: @@ -912,7 +920,7 @@ use Symfony\Component\Serializer\Normalizer\AbstractNormalizer; final class DynamicGroupProvider implements ParameterProviderInterface { - public function provide(Parameter $parameter, array $parameters = [], array $context = []): ?Operation + public function provide(Parameter $parameter, array $parameters = [], array $context = []): Operation|Parameter|null { $operation = $context['operation'] ?? null; if (!$operation) { @@ -931,6 +939,28 @@ final class DynamicGroupProvider implements ParameterProviderInterface } ``` +A provider that only transforms the value returns the new parameter: + +```php +getValue(); + + return is_string($value) ? $parameter->withValue(trim($value)) : null; + } +} +``` + ### Changing how to parse Query / Header Parameters We use our own algorithm to parse a request's query, if you want to do the parsing of `QUERY_STRING` diff --git a/core/state-providers.md b/core/state-providers.md index 0c65b5f454f..85fdc95da64 100644 --- a/core/state-providers.md +++ b/core/state-providers.md @@ -694,7 +694,8 @@ used for operation-level `provider`) or a service implementing `ApiPlatform\State\ParameterProviderInterface`. The value set by the provider remains available on the `Parameter`. Since API Platform 5.0, that value also replaces the URI variable used to fetch the resource. This lets a provider transform an identifier before the resource lookup happens, for -example to decode it: +example to decode it. Parameters are immutable (since API Platform 5.1), so the provider returns a +new `Parameter` holding the resolved value: ```php setValue(base64_decode((string) $parameter->getValue(), true)); + return $parameter->withValue(base64_decode((string) $parameter->getValue(), true)); } } ``` diff --git a/core/upgrade-guide.md b/core/upgrade-guide.md index 398d95bafa8..055588af996 100644 --- a/core/upgrade-guide.md +++ b/core/upgrade-guide.md @@ -1,5 +1,42 @@ # Upgrade Guide +## API Platform 5.0 to 5.1 + +5.1 only adds deprecations, they keep working until they are removed in 6.0. + +### API Platform 5.1 Deprecations + +#### Immutable Parameters + +Parameters live in operation metadata that is cached and shared across requests, so mutating them +leaked values from one request to the next in long-running workers. `Parameter` and `Parameters` are +now immutable. + +`Parameter::setValue()` is deprecated. A parameter provider returns the resolved value instead of +mutating the parameter it receives. `ParameterProviderInterface::provide()` now returns +`Operation|Parameter|null`: return `$parameter->withValue($value)` to change only the value, or an +`Operation` holding the replaced parameter. Callable providers, including those of +`ResponseHeaderParameter`, follow the same contract. Existing implementations returning `?Operation` +stay valid. + +```diff +-public static function decodeName(Parameter $parameter, array $parameters = [], array $context = []): void ++public static function decodeName(Parameter $parameter, array $parameters = [], array $context = []): Parameter + { +- $parameter->setValue(base64_decode((string) $parameter->getValue(), true)); ++ return $parameter->withValue(base64_decode((string) $parameter->getValue(), true)); + } +``` + +`Parameters::add()`, `remove()` and `sort()` are deprecated in favor of `with()`, `without()` and +`sorted()`, which return a new instance. In a custom metadata factory: + +```diff +-$parameters->add('key', $parameter); ++$parameters = $parameters->with('key', $parameter); + $operation = $operation->withParameters($parameters); +``` + ## API Platform 4.4 to 5.0 5.0 removes long-deprecated APIs. Components ship with a `@beta` stability flag (for example