<?php
/**
 * PHP API Versioning: Foundational Concepts
 * This code snippet illustrates the fundamental idea of routing
 * based on a version parameter, a core concept for both URL and Header strategies.
 */

interface ApiResource
{
    public function getData(string $id): array;
}

// Example: Different versions of a user resource
class UserResourceV1 implements ApiResource
{
    public function getData(string $id): array
    {
        // Simulate fetching V1 user data
        return [
            'id' => $id,
            'name' => 'John Doe V1',
            'email' => 'john.doe.v1@example.com'
        ];
    }
}

class UserResourceV2 implements ApiResource
{
    public function getData(string $id): array
    {
        // Simulate fetching V2 user data with additional fields
        return [
            'uuid' => $id, // ID might change to UUID in V2
            'fullName' => 'Jane Smith V2',
            'contactEmail' => 'jane.smith.v2@example.com',
            'status' => 'active'
        ];
    }
}

// A simplified router function to demonstrate version dispatch
function dispatchApiRequest(string $version, string $resourceName, string $id): array
{
    switch (strtolower($version)) {
        case 'v1':
            if (strtolower($resourceName) === 'users') {
                $resource = new UserResourceV1();
                return $resource->getData($id);
            }
            break;
        case 'v2':
            if (strtolower($resourceName) === 'users') {
                $resource = new UserResourceV2();
                return $resource->getData($id);
            }
            break;
        default:
            // Handle unsupported version
            header('HTTP/1.1 400 Bad Request');
            return ['error' => 'Unsupported API Version'];
    }
    header('HTTP/1.1 404 Not Found');
    return ['error' => 'Resource Not Found'];
}

// Example Usage (imagine these come from URL or Header parsing)
// $apiOutputV1 = dispatchApiRequest('v1', 'users', '123');
// $apiOutputV2 = dispatchApiRequest('v2', 'users', '456');

// print_r($apiOutputV1);
// print_r($apiOutputV2);

<?php
/**
 * PHP API Versioning: URL Approach Example
 * This example demonstrates a simple routing structure for URL-based API versioning
 * using a hypothetical micro-framework style approach.
 */

// Simulate an incoming request path
$requestPath = '/api/v2/users/123'; // Example request

// Define a map of routes, associating versions with specific controllers/handlers
$routes = [
    'v1' => [
        '/users/(\d+)' => 'UserV1Controller@show',
        '/products' => 'ProductV1Controller@index'
    ],
    'v2' => [
        '/users/(\d+)' => 'UserV2Controller@show',
        '/products' => 'ProductV2Controller@index',
        '/orders' => 'OrderV2Controller@index'
    ]
];

function handleUrlVersionedRequest(string $path, array $routes): void
{
    // Extract version from the URL path, e.g., /api/vX/resource -> vX
    if (preg_match('/^\/api\/(v\d+)\/(.*)/', $path, $matches)) {
        $version = $matches[1]; // 'v1', 'v2', etc.
        $resourcePath = '/' . $matches[2]; // '/users/123'

        if (isset($routes[$version])) {
            foreach ($routes[$version] as $pattern => $handler) {
                if (preg_match('#^' . $pattern . '$#', $resourcePath, $resourceMatches)) {
                    echo "<p>Matched route for version <strong>{$version}</strong> with resource <strong>{$resourcePath}</strong> using handler <strong>{$handler}</strong>.</p>";
                    echo "<p>Parameters: " . implode(', ', array_slice($resourceMatches, 1)) . "</p>";
                    // In a real application, we would instantiate the controller and call the method
                    // e.g., list($controllerName, $method) = explode('@', $handler);
                    // $controller = new $controllerName();
                    // call_user_func_array([$controller, $method], array_slice($resourceMatches, 1));
                    return;
                }
            }
        }
    }
    header('HTTP/1.1 404 Not Found');
    echo '<p>Error: API Version or Resource Not Found</p>';
}

// Example Usage:
handleUrlVersionedRequest($requestPath, $routes);

// Simulate a V1 request
// handleUrlVersionedRequest('/api/v1/users/456', $routes);

<?php
/**
 * PHP API Versioning: Header Approach Example
 * This example demonstrates how to implement header-based API versioning
 * by checking the Accept header or a custom X-API-Version header.
 */

// Simulate HTTP headers from an incoming request
// Example 1: Using Accept header with a custom media type
$headers1 = [
    'Accept' => 'application/vnd.myapi.v2+json',
    'Host' => 'api.example.com'
];

// Example 2: Using a custom X-API-Version header
$headers2 = [
    'Accept' => 'application/json',
    'X-API-Version' => 'v1',
    'Host' => 'api.example.com'
];

// Example 3: No version header (default to latest or a specific version)
$headers3 = [
    'Accept' => 'application/json',
    'Host' => 'api.example.com'
];

function getRequestedApiVersion(array $requestHeaders): ?string
{
    // Option 1: Using Accept header with custom media type (most RESTful)
    // e.g., Accept: application/vnd.myapi.v2+json
    if (isset($requestHeaders['Accept']) && preg_match('/application\/vnd\.myapi\.(v\d+)\+json/', $requestHeaders['Accept'], $matches)) {
        return $matches[1];
    }

    // Option 2: Using a custom X-API-Version header
    // e.g., X-API-Version: v1
    if (isset($requestHeaders['X-API-Version'])) {
        return strtolower($requestHeaders['X-API-Version']);
    }

    // Fallback: Default version if no explicit version header is provided
    // This could be 'v1', 'v2', or the latest stable version
    return 'v1'; // Default to V1 if no version specified
}

function handleHeaderVersionedRequest(array $requestHeaders, string $resourceName, string $id): void
{
    $version = getRequestedApiVersion($requestHeaders);

    echo "<p>Detected API Version: <strong>{$version}</strong></p>";

    switch ($version) {
        case 'v1':
            // Dispatch to V1 specific logic
            echo "<p>Processing request for <strong>{$resourceName}</strong> (ID: <strong>{$id}</strong>) using V1 logic.</p>";
            // Example: $controller = new UserV1Controller(); $controller->show($id);
            break;
        case 'v2':
            // Dispatch to V2 specific logic
            echo "<p>Processing request for <strong>{$resourceName}</strong> (ID: <strong>{$id}</strong>) using V2 logic.</p>" ;
            // Example: $controller = new UserV2Controller(); $controller->show($id);
            break;
        default:
            header('HTTP/1.1 400 Bad Request');
            echo '<p>Error: Unsupported API Version Specified</p>';
            break;
    }
}

// Example Usage:
// Assume resourceName and id are parsed from the base URL (e.g., /users/123)
$resourceName = 'users';
$id = '123';

handleHeaderVersionedRequest($headers1, $resourceName, $id);
echo '<hr>';
handleHeaderVersionedRequest($headers2, $resourceName, $id);
echo '<hr>';
handleVersionedRequest($headers3, $resourceName, $id);

<?php
/**
 * PHP API Versioning: Middleware Example for Header-Based Versioning
 * This demonstrates how to activate a version based on a header using a middleware pattern.
 * Similar logic can be applied for URL versioning by parsing the path.
 */

// Imagine this is part of your application's request object or context
class ApiRequestContext
{
    public ?string $apiVersion = null;
}

class VersioningMiddleware
{
    private string $defaultVersion;
    private array $supportedVersions;

    public function __construct(string $defaultVersion = 'v1', array $supportedVersions = ['v1', 'v2'])
    {
        $this->defaultVersion = $defaultVersion;
        $this->supportedVersions = $supportedVersions;
    }

    public function handle(array $requestHeaders, callable $next, ApiRequestContext $context): void
    {
        $requestedVersion = $this->defaultVersion; // Start with default

        // Prioritize custom X-API-Version header if present
        if (isset($requestHeaders['X-API-Version'])) {
            $headerVersion = strtolower($requestHeaders['X-API-Version']);
            if (in_array($headerVersion, $this->supportedVersions)) {
                $requestedVersion = $headerVersion;
            }
        } else if (isset($requestHeaders['Accept']) && preg_match('/application\/vnd\.myapi\.(v\d+)\+json/', $requestHeaders['Accept'], $matches)) {
            // Fallback to Accept header if X-API-Version is not present
            $acceptVersion = $matches[1];
            if (in_array($acceptVersion, $this->supportedVersions)) {
                $requestedVersion = $acceptVersion;
            }
        }

        $context->apiVersion = $requestedVersion;

        // Pass control to the next middleware or the main application logic
        $next($context);
    }
}

// Simulate a request dispatch pipeline
function runApiRequest(array $headers, callable $apiLogic):
{
    $context = new ApiRequestContext();
    $middleware = new VersioningMiddleware('v1', ['v1', 'v2']);

    $middleware->handle($headers, function(ApiRequestContext $ctx) use ($apiLogic) {
        // This is where your actual API route/controller logic would reside
        $apiLogic($ctx);
    }, $context);
}

// Example API logic that uses the version from the context
$myApiLogic = function(ApiRequestContext $ctx) {
    if (isset($ctx->apiVersion)) {
        echo "<p>API Logic executing for version: <strong>{$ctx->apiVersion}</strong></p>";
        if ($ctx->apiVersion === 'v2') {
            echo "<p>Applying V2 specific features.</p>";
        } else {
            echo "<p>Applying V1 fallback features.</p>";
        }
    } else {
        echo "<p>Error: No API version detected.</p>";
    }
};

// Test cases
runApiRequest(['X-API-Version' => 'v2'], $myApiLogic);
echo '<hr>';
runApiRequest(['Accept' => 'application/vnd.myapi.v1+json'], $myApiLogic);
echo '<hr>';
runApiRequest([], $myApiLogic); // Should default to V1

<?php
/**
 * PHP API Versioning: Deprecation Example using Middleware
 * This snippet demonstrates how to warn clients about deprecated API versions
 * and eventually block access to sunset versions.
 */

class ApiVersionManager
{
    private string $currentVersion = 'v2';
    private array $deprecatedVersions = ['v1' => '2025-06-01']; // Version => Sunset Date
    private array $sunsetVersions = []; // Versions after their sunset date

    public function isVersionDeprecated(string $version): bool
    {
        return isset($this->deprecatedVersions[$version]) && strtotime($this->deprecatedVersions[$version]) > time();
    }

    public function isVersionSunset(string $version): bool
    {
        return isset($this->deprecatedVersions[$version]) && strtotime($this->deprecatedVersions[$version]) <= time();
    }

    public function getCurrentVersion(): string
    {
        return $this->currentVersion;
    }
}

class DeprecationMiddleware
{
    private ApiVersionManager $versionManager;

    public function __construct(ApiVersionManager $versionManager)
    {
        $this->versionManager = $versionManager;
    }

    public function handle(ApiRequestContext $context, callable $next): void
    {
        $apiVersion = $context->apiVersion ?? $this->versionManager->getCurrentVersion();

        if ($this->versionManager->isVersionSunset($apiVersion)) {
            header('HTTP/1.1 410 Gone');
            echo '<p>Error: API Version ' . $apiVersion . ' has been sunset and is no longer available.</p>';
            exit; // Terminate request for sunset versions
        }

        if ($this->versionManager->isVersionDeprecated($apiVersion)) {
            header('X-API-Warning: This API version (' . $apiVersion . ') is deprecated and will be sunset on ' . $this->versionManager->deprecatedVersions[$apiVersion] . '. Please upgrade to ' . $this->versionManager->getCurrentVersion() . '.', false);
            // Also consider logging this for monitoring usage of deprecated versions
        }

        $next($context);
    }
}

// Simulate the full request pipeline
function runVersionedRequestWithDeprecation(array $headers, string $requestedVersion, callable $apiLogic):
{
    $context = new ApiRequestContext();
    $context->apiVersion = $requestedVersion; // Manually set for demonstration

    $versionManager = new ApiVersionManager();
    $deprecationMiddleware = new DeprecationMiddleware($versionManager);

    // Assume VersioningMiddleware (from previous example) has already set $context->apiVersion
    $deprecationMiddleware->handle($context, function(ApiRequestContext $ctx) use ($apiLogic) {
        $apiLogic($ctx);
    });
}

// Example API logic
$apiCoreLogic = function(ApiRequestContext $ctx) {
    echo "<p>API Core Logic for version: <strong>{$ctx->apiVersion}</strong></p>";
};

// Test cases
runVersionedRequestWithDeprecation([], 'v1', $apiCoreLogic); // v1 is deprecated, sends warning header
echo '<hr>';
runVersionedRequestWithDeprecation([], 'v2', $apiCoreLogic); // v2 is current, no warning
echo '<hr>';

// To simulate sunset, manually adjust date or $sunsetVersions
// For example, if 'v1' sunset date was in the past:
// $versionManager->deprecatedVersions = ['v1' => '2023-01-01']; // This would trigger 410 Gone