Story: Introduce the generic spatial encoding API #25

Goal

Replace the current Writer public API with the generic, immutable encoding API defined by #19 and adapt all existing encoding strategies to the new EncodeStrategyInterface.

This Story is the architectural core of #19. It changes the public orchestration contract while preserving the existing format-specific encoding behavior.

Scope

Introduce the public strategy contract:

interface EncoderInterface
{
    public function encode(SpatialInterface $spatial): mixed;
}

Introduce the public encoder:

final readonly class Encoder
{
    public function __construct(
        private EncoderInterface $strategy,
    ) {
    }

    public function encode(SpatialInterface $spatial): mixed
    {
        return $this->strategy->execute($spatial);
    }
}

Adapt all existing encoding implementations on main to the new contract:

• WKT
• EWKT
• WKB
• EWKB
• GeoJSON
• MySQL spatial binary format

Remove the obsolete Writer API and any superseded public contracts. No backward-compatibility layer, deprecation mechanism, alias, or transitional API is required.

Acceptance criteria

• A public EncodeStrategyInterface exists.
• EncodeStrategyInterface declares exactly execute(SpatialInterface $spatial): mixed.
• A public Encoder class exists and is declared final readonly.
• Encoder receives an EncodeStrategyInterface through constructor injection.
• Encoder::encode(SpatialInterface $spatial): mixed delegates encoding to the injected strategy.
• The exact supplied SpatialInterface instance is passed to the strategy and is not mutated by the encoder.
• The value returned by the strategy is returned unchanged by Encoder::encode().
• Strategies returning different PHP types can implement the same generic contract.
• Existing WKT, EWKT, WKB, EWKB, GeoJSON, and MySQL encoding implementations use the new strategy contract.
• Existing format-specific behavior and supported spatial representations are preserved.
• Existing format-specific tests are adapted to the new API and remain successful.
• The obsolete Writer API and superseded contracts are removed.
• No setter or other mutable strategy replacement mechanism is introduced.
• No backward-compatibility or deprecation mechanism is introduced.

Format-semantics gate

This Story MUST NOT intentionally change format-specific encoding semantics.

The migration must preserve the behavior currently covered by the existing test suite. If an existing behavior is discovered to require a semantic correction for compliance with ISO/IEC 13249-3, the applicable ISO 191xx standards, OGC specifications, RFC 7946, or a vendor-specific format, that correction must be handled explicitly outside this architectural Story unless required to make the new contract function.

Testing and quality

Tests must cover the generic contract itself in addition to the existing format-specific suites.

The complete standard LongitudeOne test and quality pipeline must pass.

Out of scope

• Repository/package/namespace renaming.
• New encoding formats.
• New spatial representation support.
• Semantic changes to existing encoding formats.
• Decoding.
• Spatial transformation or reprojection.
• Backward compatibility with the former Writer API.

Parent Epic

#19

Estimate

5 Story Points