Create API Versioning

API Versioning Generator

Creates API Versioning infrastructure with multiple resolution strategies and deprecation support.

When to Use

Component Characteristics

ApiVersion (Value Object)

• Immutable version representation
• Major and minor version numbers
• Comparison methods (equals, greaterThan, lessThan)
• String parsing (fromString "v1.2")

VersionResolverInterface

• Extracts version from PSR-7 request
• Returns null if version not found
• Strategy pattern for different sources

Resolution Strategies

• UriPrefixVersionResolver — Extracts from URI path (/v1/orders)
• AcceptHeaderVersionResolver — Extracts from Accept header (application/vnd.api.v1+json)
• QueryParamVersionResolver — Extracts from query string (?version=1)
• CompositeVersionResolver — Tries multiple strategies in order

VersionMiddleware

• PSR-15 middleware
• Resolves version via strategy
• Adds version to request attributes
• Returns 400 if version required but missing

Generation Process

Step 1: Generate Domain Components

Path: src/Domain/Shared/Api/

1. ApiVersion.php — Immutable version value object
2. VersionResolverInterface.php — Version resolution contract

Step 2: Generate Presentation Components

Path: src/Presentation/Middleware/

1. UriPrefixVersionResolver.php — URI path strategy
2. AcceptHeaderVersionResolver.php — Content negotiation strategy
3. QueryParamVersionResolver.php — Query parameter strategy
4. CompositeVersionResolver.php — Composite strategy
5. VersionMiddleware.php — PSR-15 middleware
6. DeprecationHeaderMiddleware.php — Deprecation/Sunset headers

Step 3: Generate Tests

1. ApiVersionTest.php — Value object tests
2. UriPrefixVersionResolverTest.php — URI parsing tests
3. AcceptHeaderVersionResolverTest.php — Header parsing tests
4. VersionMiddlewareTest.php — Middleware behavior tests

File Placement

Naming Conventions

Quick Template Reference

ApiVersion

final readonly class ApiVersion
{
    public function __construct(
        public int $major,
        public int $minor = 0
    ) {
        if ($this->major < 1) {
            throw new \InvalidArgumentException('Major version must be at least 1');
        }
    }

    public static function fromString(string $version): self;
    public function toString(): string;
    public function equals(self $other): bool;
    public function greaterThan(self $other): bool;
}

VersionResolverInterface

interface VersionResolverInterface
{
    public function resolve(ServerRequestInterface $request): ?ApiVersion;
}

Usage Example

// Create composite resolver
$resolver = new CompositeVersionResolver([
    new UriPrefixVersionResolver(),
    new AcceptHeaderVersionResolver(),
    new QueryParamVersionResolver(),
]);

// Middleware adds version to request attributes
$middleware = new VersionMiddleware($resolver, defaultVersion: new ApiVersion(1));

// In action/controller
$version = $request->getAttribute('api_version');
if ($version->greaterThan(new ApiVersion(1))) {
    return $this->respondV2($data);
}

Strategy Comparison

Anti-patterns to Avoid

References

For complete PHP templates and examples, see:

• references/templates.md — ApiVersion, resolvers, middleware, deprecation templates
• references/examples.md — Framework integration and tests

Converted and distributed by TomeVault — claim your Tome and manage your conversions.