Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions core/filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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) {
Expand All @@ -931,6 +939,28 @@ final class DynamicGroupProvider implements ParameterProviderInterface
}
```

A provider that only transforms the value returns the new parameter:

```php
<?php
// src/State/TrimProvider.php
namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\Metadata\Parameter;
use ApiPlatform\State\ParameterProviderInterface;

final class TrimProvider implements ParameterProviderInterface
{
public function provide(Parameter $parameter, array $parameters = [], array $context = []): Operation|Parameter|null
{
$value = $parameter->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`
Expand Down
7 changes: 4 additions & 3 deletions core/state-providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<?php
Expand Down Expand Up @@ -726,9 +727,9 @@ class Base64UriVariableDummy
#[ORM\Column]
public string $name;

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));
}
}
```
Expand Down
37 changes: 37 additions & 0 deletions core/upgrade-guide.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading