Story: Migrate existing decoder strategies to typed input contracts #18

Context

Typed input contracts have been introduced for decoder strategies.

Each strategy can now explicitly declare the input representation or representations it supports by implementing one or more specialized interfaces:

• StringDecoderStrategyInterface
• ArrayDecoderStrategyInterface
• ObjectDecoderStrategyInterface

The central Decoder is responsible for checking compatibility between the supplied input and the configured strategy before delegating the decoding operation.

Existing decoder strategies must now be migrated to these specialized contracts.

Objective

Migrate every existing decoder strategy to the typed input contracts according to the input representations it actually supports.

Each strategy must expose the narrowest valid native PHP type for its decode() parameter without changing its existing decoding behavior.

Implementation

For each existing decoder strategy:

• identify the input representation or representations currently supported;
• implement the corresponding specialized strategy interface or interfaces;
• narrow the native decode() parameter type to the supported representation or union of representations;
• preserve existing format-specific validation;
• preserve existing exception behavior unless required by the new contract;
• adapt existing tests to the new method signatures and contracts.

A strategy supporting a single representation must expose that representation directly:

final class ExampleStrategy implements StringDecoderStrategyInterface
{
    public function decode(string $data): SpatialInterface
    {
        // Existing decoding implementation.
    }
}

A strategy supporting several representations must implement all corresponding interfaces and expose a compatible union type:

final class ExampleStrategy implements
    StringDecoderStrategyInterface,
    ArrayDecoderStrategyInterface
{
    public function decode(string|array $data): SpatialInterface
    {
        // Existing decoding implementation.
    }
}

No strategy must advertise support for an input representation that it cannot actually decode.

Acceptance criteria

• Every existing decoder strategy implements at least one specialized decoder strategy interface.
• Each strategy implements only the input contracts it actually supports.
• Each decode() method uses the narrowest native PHP parameter type compatible with its implemented contracts.
• Strategies supporting multiple input representations implement all corresponding specialized interfaces.
• Existing supported inputs continue to produce the same decoded spatial objects.
• Existing format-specific validation remains unchanged.
• Existing exception behavior remains unchanged unless directly affected by the typed input contract.
• Tests are updated to exercise each strategy through its new typed contract.
• Existing decoding tests continue to pass for all supported inputs.
• No new input representation is introduced as part of the migration.
• No automatic conversion between input representations is introduced.
• All existing quality and CI gates remain green.

Out of scope

• Changes to the central Decoder dispatch mechanism.
• Changes to the specialized strategy interfaces.
• Public API documentation.
• New decoder strategies.
• New input representations.
• Changes to format-specific decoding behavior unrelated to the contract migration.