Implemented API evolution pattern

config/pipeline.php

@@ -6,6 +6,7 @@
 use Api\App\Middleware\AuthenticationMiddleware;
 use Api\App\Middleware\AuthorizationMiddleware;
 use Api\App\Middleware\ContentNegotiationMiddleware;
+use Api\App\Middleware\DeprecationMiddleware;
 use Dot\ErrorHandler\ErrorHandlerInterface;
 use Dot\ResponseHeader\Middleware\ResponseHeaderMiddleware;
 use Mezzio\Application;
@@ -61,6 +62,7 @@
     $app->pipe(MethodNotAllowedMiddleware::class);
 
     $app->pipe(ContentNegotiationMiddleware::class);
+    $app->pipe(DeprecationMiddleware::class);
 
     $app->pipe(ResponseHeaderMiddleware::class);
 

src/App/src/Attribute/MethodDeprecation.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Api\App\Attribute;
+
+use Api\App\Exception\DeprecationSunsetException;
+use Api\App\Message;
+use Attribute;
+use Laminas\Validator\Date;
+
+use function sprintf;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+final readonly class MethodDeprecation
+{
+    public function __construct(public string $sunset, public string $link, public string $deprecationReason = '')
+    {
+        if (! (new Date())->isValid($sunset)) {
+            throw new DeprecationSunsetException(sprintf(Message::INVALID_VALUE, 'sunset'));
+        }
+    }
+}

src/App/src/Attribute/ResourceDeprecation.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Api\App\Attribute;
+
+use Api\App\Exception\DeprecationSunsetException;
+use Api\App\Message;
+use Attribute;
+use Laminas\Validator\Date;
+
+use function sprintf;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final readonly class ResourceDeprecation
+{
+    public function __construct(public string $sunset, public string $link, public string $deprecationReason = '')
+    {
+        if (! (new Date())->isValid($sunset)) {
+            throw new DeprecationSunsetException(sprintf(Message::INVALID_VALUE, 'sunset'));
+        }
+    }
+}

src/App/src/ConfigProvider.php

@@ -11,10 +11,12 @@
 use Api\App\Factory\EntityListenerResolverFactory;
 use Api\App\Factory\RouteListCommandFactory;
 use Api\App\Factory\TokenGenerateCommandFactory;
+use Api\App\Handler\ErrorReportHandler;
 use Api\App\Handler\HomeHandler;
 use Api\App\Middleware\AuthenticationMiddleware;
 use Api\App\Middleware\AuthorizationMiddleware;
 use Api\App\Middleware\ContentNegotiationMiddleware;
+use Api\App\Middleware\DeprecationMiddleware;
 use Api\App\Middleware\ErrorResponseMiddleware;
 use Api\App\Service\ErrorReportService;
 use Api\App\Service\ErrorReportServiceInterface;
@@ -66,10 +68,12 @@
                 AuthenticationMiddleware::class       => AuthenticationMiddlewareFactory::class,
                 AuthorizationMiddleware::class        => AttributedServiceFactory::class,
                 ContentNegotiationMiddleware::class   => AttributedServiceFactory::class,
+                DeprecationMiddleware::class          => AttributedServiceFactory::class,
                 Environment::class                    => TwigEnvironmentFactory::class,
                 TwigExtension::class                  => TwigExtensionFactory::class,
                 TwigRenderer::class                   => TwigRendererFactory::class,
                 HomeHandler::class                    => AttributedServiceFactory::class,
+                ErrorReportHandler::class             => AttributedServiceFactory::class,
                 ErrorResponseMiddleware::class        => AttributedServiceFactory::class,
                 RouteListCommand::class               => RouteListCommandFactory::class,
                 TokenGenerateCommand::class           => TokenGenerateCommandFactory::class,

src/App/src/Exception/DeprecationConflictException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Api\App\Exception;
+
+use RuntimeException;
+
+class DeprecationConflictException extends RuntimeException
+{
+}

src/App/src/Exception/DeprecationSunsetException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Api\App\Exception;
+
+use RuntimeException;
+
+class DeprecationSunsetException extends RuntimeException
+{
+}

src/App/src/Handler/ErrorReportHandler.php

@@ -4,6 +4,7 @@
 
 namespace Api\App\Handler;
 
+use Api\App\Attribute\MethodDeprecation;
 use Api\App\Exception\ForbiddenException;
 use Api\App\Message;
 use Api\App\Service\ErrorReportServiceInterface;
@@ -38,6 +39,11 @@ public function __construct(
      * @throws ForbiddenException
      * @throws RuntimeException
      */
+    #[MethodDeprecation(
+        sunset: '2038-01-01',
+        link: 'https://docs.dotkernel.org/api-documentation/v5/core-features/versioning',
+        deprecationReason: 'Method deprecation example.',
+    )]
     public function post(ServerRequestInterface $request): ResponseInterface
     {
         $this->errorReportService

src/App/src/Handler/HomeHandler.php

@@ -4,12 +4,18 @@
 
 namespace Api\App\Handler;
 
+use Api\App\Attribute\ResourceDeprecation;
 use Dot\DependencyInjection\Attribute\Inject;
 use Mezzio\Hal\HalResponseFactory;
 use Mezzio\Hal\ResourceGenerator;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
+#[ResourceDeprecation(
+    sunset: '2038-01-01',
+    link: 'https://docs.dotkernel.org/api-documentation/v5/core-features/versioning',
+    deprecationReason: 'Resource deprecation example.',
+)]
 class HomeHandler implements RequestHandlerInterface
 {
     use HandlerTrait;

src/App/src/Message.php

@@ -18,19 +18,20 @@ class Message
     public const INVALID_CLIENT_ID                = 'Invalid client_id.';
     public const INVALID_CONFIG                   = 'Invalid configuration value: \'%s\'';
     public const INVALID_VALUE                    = 'The value specified for \'%s\' is invalid.';
+    public const MAIL_NOT_SENT_TO                 = 'Could not send mail to \'%s\'.';
     public const MAIL_SENT_RECOVER_IDENTITY       = 'If the provided email identifies an account in our system, '
     . 'you will receive an email with your account\'s identity.';
     public const MAIL_SENT_RESET_PASSWORD         = 'If the provided email identifies an account in our system, '
     . 'you will receive an email with further instructions on resetting your account\'s password.';
     public const MAIL_SENT_USER_ACTIVATION        = 'User activation mail has been successfully sent to \'%s\'';
-    public const MAIL_NOT_SENT_TO                 = 'Could not send mail to \'%s\'.';
     public const MISSING_CONFIG                   = 'Missing configuration value: \'%s\'.';
     public const RESET_PASSWORD_EXPIRED           = 'Password reset request for hash: \'%s\' is invalid (expired).';
     public const RESET_PASSWORD_NOT_FOUND         = 'Could not find password reset request identified by hash: \'%s\'';
     public const RESET_PASSWORD_OK                = 'Password successfully modified.';
     public const RESET_PASSWORD_USED              = 'Password reset request for hash: \'%s\' is invalid (used).';
     public const RESET_PASSWORD_VALID             = 'Password reset request for hash: \'%s\' is valid.';
     public const RESOURCE_NOT_ALLOWED             = 'You are not allowed to access this resource.';
+    public const RESTRICTION_DEPRECATION          = 'Cannot use both `%s` and `%s` attributes on the same object.';
     public const RESTRICTION_IMAGE                = 'File must be an image (jpg, png).';
     public const RESTRICTION_ROLES                = 'User accounts must have at least one role.';
     public const ROLE_NOT_FOUND                   = 'Role not found.';

src/App/src/Middleware/DeprecationMiddleware.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Api\App\Middleware;
+
+use Api\App\Attribute\MethodDeprecation;
+use Api\App\Attribute\ResourceDeprecation;
+use Api\App\Exception\DeprecationConflictException;
+use Api\App\Handler\ResponseTrait;
+use Api\App\Message;
+use Laminas\Stratigility\MiddlewarePipe;
+use Mezzio\Middleware\LazyLoadingMiddleware;
+use Mezzio\Router\RouteResult;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use ReflectionClass;
+use ReflectionException;
+use ReflectionMethod;
+
+use function array_key_exists;
+use function array_keys;
+use function sprintf;
+
+class DeprecationMiddleware implements MiddlewareInterface
+{
+    use ResponseTrait;
+
+    public const RESOURCE_DEPRECATION_ATTRIBUTE = ResourceDeprecation::class;
+    public const METHOD_DEPRECATION_ATTRIBUTE   = MethodDeprecation::class;
+
+    /**
+     * @throws ReflectionException
+     */
+    public function process(
+        ServerRequestInterface $request,
+        RequestHandlerInterface $handler
+    ): ResponseInterface {
+        $response    = $handler->handle($request);
+        $routeResult = $request->getAttribute(RouteResult::class);
+        if (! $routeResult instanceof RouteResult || $routeResult->isFailure()) {
+            return $response;
+        }
+
+        $reflectionHandler = null;
+        $matchedRoute      = $routeResult->getMatchedRoute();
+        if (! $matchedRoute) {
+            return $response;
+        }
+
+        $routeMiddleware = $matchedRoute->getMiddleware();
+        if ($routeMiddleware instanceof LazyLoadingMiddleware) {
+            /** @var class-string $routeMiddlewareName */
+            $routeMiddlewareName       = $routeMiddleware->middlewareName;
+            $reflectionMiddlewareClass = new ReflectionClass($routeMiddlewareName);
+            if ($reflectionMiddlewareClass->implementsInterface(RequestHandlerInterface::class)) {
+                $reflectionHandler = $reflectionMiddlewareClass;
+            }
+        } elseif ($routeMiddleware instanceof MiddlewarePipe) {
+            $reflectionClass    = new ReflectionClass($routeMiddleware);
+            $middlewarePipeline = $reflectionClass->getProperty('pipeline')->getValue($routeMiddleware);
+            for ($middlewarePipeline->rewind(); $middlewarePipeline->valid(); $middlewarePipeline->next()) {
+                $reflectionMiddlewareClass = new ReflectionClass($middlewarePipeline->current()->middlewareName);
+                if ($reflectionMiddlewareClass->implementsInterface(RequestHandlerInterface::class)) {
+                    $reflectionHandler = $reflectionMiddlewareClass;
+                }
+            }
+        }
+
+        if (! $reflectionHandler) {
+            return $response;
+        }
+
+        $attributes = $this->getAttributes($reflectionHandler, self::RESOURCE_DEPRECATION_ATTRIBUTE);
+        foreach ($reflectionHandler->getMethods() as $method) {
+            $methodRef   = new ReflectionMethod($method->class, $method->name);
+            $attributes += $this->getAttributes($methodRef, self::METHOD_DEPRECATION_ATTRIBUTE);
+        }
+
+        if ([self::RESOURCE_DEPRECATION_ATTRIBUTE, self::METHOD_DEPRECATION_ATTRIBUTE] === array_keys($attributes)) {
+            throw new DeprecationConflictException(
+                sprintf(
+                    Message::RESTRICTION_DEPRECATION,
+                    self::RESOURCE_DEPRECATION_ATTRIBUTE,
+                    self::METHOD_DEPRECATION_ATTRIBUTE
+                )
+            );
+        }
+
+        $sunset = null;
+        $link   = null;
+        if (array_key_exists(self::RESOURCE_DEPRECATION_ATTRIBUTE, $attributes)) {
+            $sunset = $attributes[self::RESOURCE_DEPRECATION_ATTRIBUTE]['sunset'];
+            $link   = $attributes[self::RESOURCE_DEPRECATION_ATTRIBUTE]['link'];
+        }
+
+        if (array_key_exists(self::METHOD_DEPRECATION_ATTRIBUTE, $attributes)) {
+            $sunset = $attributes[self::METHOD_DEPRECATION_ATTRIBUTE]['sunset'];
+            $link   = $attributes[self::METHOD_DEPRECATION_ATTRIBUTE]['link'];
+        }
+
+        if ($sunset !== null) {
+            $response = $response->withHeader('sunset', $sunset);
+        }
+
+        if ($link !== null) {
+            $response = $response->withHeader('link', $link);
+        }
+
+        return $response;
+    }
+
+    /**
+     * @param class-string $type
+     */
+    public function getAttributes(ReflectionClass|ReflectionMethod $reflection, string $type): array
+    {
+        $attributes = [];
+        foreach ($reflection->getAttributes($type) as $attribute) {
+            $attribute->newInstance();
+            $attributes[$attribute->getName()] = $attribute->getArguments();
+        }
+
+        return $attributes;
+    }
+}

test/Unit/App/Attribute/MethodDeprecationTest.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ApiTest\Unit\App\Attribute;
+
+use Api\App\Attribute\MethodDeprecation;
+use Api\App\Exception\DeprecationSunsetException;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+
+class MethodDeprecationTest extends TestCase
+{
+    public function testInvalidDateThrowsException(): void
+    {
+        $class = new class {
+            #[MethodDeprecation(
+                sunset: 'invalid-01-01',
+                link: 'test-link',
+                deprecationReason: 'test-deprecation-reason',
+            )]
+            public function test(): void
+            {
+            }
+        };
+
+        $reflectionClass = new ReflectionClass($class);
+        $attributes      = $this->getAttributes($reflectionClass);
+
+        $this->expectException(DeprecationSunsetException::class);
+
+        $attributes[0]->newInstance();
+    }
+
+    public function testValidDatePassesValidation(): void
+    {
+        $class = new class {
+            #[MethodDeprecation(
+                sunset: '2038-01-01',
+                link: 'test-link',
+                deprecationReason: 'test-deprecation-reason',
+            )]
+            public function test(): void
+            {
+            }
+        };
+
+        $reflectionClass = new ReflectionClass($class);
+        $attributes      = $this->getAttributes($reflectionClass);
+
+        $attribute = $attributes[0]->newInstance();
+
+        $this->assertSame('2038-01-01', $attribute->sunset);
+        $this->assertSame('test-link', $attribute->link);
+        $this->assertSame('test-deprecation-reason', $attribute->deprecationReason);
+    }
+
+    private function getAttributes(ReflectionClass $reflectionClass): array
+    {
+        $methods = $reflectionClass->getMethods();
+        return $methods[0]->getAttributes(MethodDeprecation::class);
+    }
+}