Merge pull request #3322 from limarkxx/add-psalm

Add template generics for PSR-11 implementations in PHPStan and Psalm

Slim/App.php

@@ -31,6 +31,11 @@
 
 use function strtoupper;
 
+/**
+ * @api
+ * @template TContainerInterface of (ContainerInterface|null)
+ * @template-extends RouteCollectorProxy<TContainerInterface>
+ */
 class App extends RouteCollectorProxy implements RequestHandlerInterface
 {
     /**
@@ -44,6 +49,9 @@ class App extends RouteCollectorProxy implements RequestHandlerInterface
 
     protected MiddlewareDispatcherInterface $middlewareDispatcher;
 
+    /**
+     * @param TContainerInterface $container
+     */
     public function __construct(
         ResponseFactoryInterface $responseFactory,
         ?ContainerInterface $container = null,
@@ -89,6 +97,7 @@ public function getMiddlewareDispatcher(): MiddlewareDispatcherInterface
 
     /**
      * @param MiddlewareInterface|string|callable $middleware
+     * @return App<TContainerInterface>
      */
     public function add($middleware): self
     {
@@ -98,6 +107,7 @@ public function add($middleware): self
 
     /**
      * @param MiddlewareInterface $middleware
+     * @return App<TContainerInterface>
      */
     public function addMiddleware(MiddlewareInterface $middleware): self
     {

Slim/CallableResolver.php

@@ -26,12 +26,19 @@
 use function preg_match;
 use function sprintf;
 
+/**
+ * @template TContainerInterface of (ContainerInterface|null)
+ */
 final class CallableResolver implements AdvancedCallableResolverInterface
 {
     public static string $callablePattern = '!^([^\:]+)\:([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)$!';
 
+    /** @var TContainerInterface $container */
     private ?ContainerInterface $container;
 
+    /**
+     * @param TContainerInterface $container
+     */
     public function __construct(?ContainerInterface $container = null)
     {
         $this->container = $container;
@@ -120,11 +127,10 @@ private function isMiddleware($toResolve): bool
      */
     private function resolveSlimNotation(string $toResolve): array
     {
+        /** @psalm-suppress ArgumentTypeCoercion */
         preg_match(CallableResolver::$callablePattern, $toResolve, $matches);
         [$class, $method] = $matches ? [$matches[1], $matches[2]] : [$toResolve, null];
 
-        /** @var string $class */
-        /** @var string|null $method */
         if ($this->container && $this->container->has($class)) {
             $instance = $this->container->get($class);
             if (!is_object($instance)) {

Slim/Error/Renderers/HtmlErrorRenderer.php

@@ -39,7 +39,6 @@ private function renderExceptionFragment(Throwable $exception): string
     {
         $html = sprintf('<div><strong>Type:</strong> %s</div>', get_class($exception));
 
-        /** @var int|string $code */
         $code = $exception->getCode();
         $html .= sprintf('<div><strong>Code:</strong> %s</div>', $code);
 

Slim/Error/Renderers/JsonErrorRenderer.php

@@ -43,7 +43,6 @@ public function __invoke(Throwable $exception, bool $displayErrorDetails): strin
      */
     private function formatExceptionFragment(Throwable $exception): array
     {
-        /** @var int|string $code */
         $code = $exception->getCode();
         return [
             'type' => get_class($exception),

Slim/Error/Renderers/PlainTextErrorRenderer.php

@@ -43,7 +43,7 @@ private function formatExceptionFragment(Throwable $exception): string
         $text = sprintf("Type: %s\n", get_class($exception));
 
         $code = $exception->getCode();
-        /** @var int|string $code */
+
         $text .= sprintf("Code: %s\n", $code);
 
         $text .= sprintf("Message: %s\n", $exception->getMessage());

Slim/Exception/HttpBadRequestException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpBadRequestException extends HttpSpecializedException
 {
     /**

Slim/Exception/HttpException.php

@@ -15,6 +15,7 @@
 use Throwable;
 
 /**
+ * @api
  * @method int getCode()
  */
 class HttpException extends RuntimeException

Slim/Exception/HttpForbiddenException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpForbiddenException extends HttpSpecializedException
 {
     /**

Slim/Exception/HttpGoneException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpGoneException extends HttpSpecializedException
 {
     /**

Slim/Exception/HttpInternalServerErrorException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpInternalServerErrorException extends HttpSpecializedException
 {
     /**

Slim/Exception/HttpNotImplementedException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpNotImplementedException extends HttpSpecializedException
 {
     /**

Slim/Exception/HttpTooManyRequestsException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpTooManyRequestsException extends HttpSpecializedException
 {
     /**

Slim/Exception/HttpUnauthorizedException.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Exception;
 
+/** @api */
 class HttpUnauthorizedException extends HttpSpecializedException
 {
     /**

Slim/Factory/AppFactory.php

@@ -24,6 +24,7 @@
 use Slim\Interfaces\RouteCollectorInterface;
 use Slim\Interfaces\RouteResolverInterface;
 
+/** @api */
 class AppFactory
 {
     protected static ?Psr17FactoryProviderInterface $psr17FactoryProvider = null;
@@ -44,6 +45,11 @@ class AppFactory
 
     protected static bool $slimHttpDecoratorsAutomaticDetectionEnabled = true;
 
+    /**
+     * @template TContainerInterface of (ContainerInterface|null)
+     * @param TContainerInterface $container
+     * @return (TContainerInterface is ContainerInterface ? App<TContainerInterface> : App<ContainerInterface|null>)
+     */
     public static function create(
         ?ResponseFactoryInterface $responseFactory = null,
         ?ContainerInterface $container = null,
@@ -63,6 +69,11 @@ public static function create(
         );
     }
 
+    /**
+     * @template TContainerInterface of (ContainerInterface)
+     * @param TContainerInterface $container
+     * @return App<TContainerInterface>
+     */
     public static function createFromContainer(ContainerInterface $container): App
     {
         $responseFactory = $container->has(ResponseFactoryInterface::class)

Slim/Factory/ServerRequestCreatorFactory.php

@@ -17,6 +17,7 @@
 use Slim\Interfaces\Psr17FactoryProviderInterface;
 use Slim\Interfaces\ServerRequestCreatorInterface;
 
+/** @api */
 class ServerRequestCreatorFactory
 {
     protected static ?Psr17FactoryProviderInterface $psr17FactoryProvider = null;

Slim/Handlers/ErrorHandler.php

@@ -43,6 +43,7 @@
  *
  * It outputs the error message and diagnostic information in one of the following formats:
  * JSON, XML, Plain Text or HTML based on the Accept header.
+ * @api
  */
 class ErrorHandler implements ErrorHandlerInterface
 {

Slim/Handlers/Strategies/RequestResponseArgs.php

@@ -18,6 +18,7 @@
 
 /**
  * Route callback strategy with route parameters as individual arguments.
+ * @api
  */
 class RequestResponseArgs implements InvocationStrategyInterface
 {

Slim/Handlers/Strategies/RequestResponseNamedArgs.php

@@ -17,6 +17,7 @@
 
 /**
  * Route callback strategy with route parameters as individual arguments.
+ * @api
  */
 class RequestResponseNamedArgs implements InvocationStrategyInterface
 {

Slim/Interfaces/MiddlewareDispatcherInterface.php

@@ -13,6 +13,7 @@
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
+/** @api */
 interface MiddlewareDispatcherInterface extends RequestHandlerInterface
 {
     /**

Slim/Interfaces/Psr17FactoryProviderInterface.php

@@ -10,6 +10,7 @@
 
 namespace Slim\Interfaces;
 
+/** @api */
 interface Psr17FactoryProviderInterface
 {
     /**

Slim/Interfaces/RouteCollectorInterface.php

@@ -13,6 +13,7 @@
 use InvalidArgumentException;
 use RuntimeException;
 
+/** @api */
 interface RouteCollectorInterface
 {
     /**

Slim/Interfaces/RouteCollectorProxyInterface.php

@@ -14,12 +14,19 @@
 use Psr\Http\Message\ResponseFactoryInterface;
 use Psr\Http\Message\UriInterface;
 
+/**
+ * @api
+ * @template TContainerInterface of (ContainerInterface|null)
+ */
 interface RouteCollectorProxyInterface
 {
     public function getResponseFactory(): ResponseFactoryInterface;
 
     public function getCallableResolver(): CallableResolverInterface;
 
+    /**
+     * @return TContainerInterface
+     */
     public function getContainer(): ?ContainerInterface;
 
     public function getRouteCollector(): RouteCollectorInterface;
@@ -31,6 +38,7 @@ public function getBasePath(): string;
 
     /**
      * Set the RouteCollectorProxy's base path
+     * @return RouteCollectorProxyInterface<TContainerInterface>
      */
     public function setBasePath(string $basePath): RouteCollectorProxyInterface;
 

Slim/Interfaces/RouteGroupInterface.php

@@ -13,6 +13,7 @@
 use Psr\Http\Server\MiddlewareInterface;
 use Slim\MiddlewareDispatcher;
 
+/** @api */
 interface RouteGroupInterface
 {
     public function collectRoutes(): RouteGroupInterface;
@@ -31,6 +32,7 @@ public function addMiddleware(MiddlewareInterface $middleware): RouteGroupInterf
 
     /**
      * Append the group's middleware to the MiddlewareDispatcher
+     * @param MiddlewareDispatcher<\Psr\Container\ContainerInterface|null> $dispatcher
      */
     public function appendMiddlewareToDispatcher(MiddlewareDispatcher $dispatcher): RouteGroupInterface;
 

Slim/Interfaces/RouteInterface.php

@@ -14,6 +14,7 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 
+/** @api */
 interface RouteInterface
 {
     /**

Slim/Interfaces/RouteParserInterface.php

@@ -14,6 +14,7 @@
 use Psr\Http\Message\UriInterface;
 use RuntimeException;
 
+/** @api */
 interface RouteParserInterface
 {
     /**

Slim/Middleware/BodyParsingMiddleware.php

@@ -33,6 +33,7 @@
 
 use const LIBXML_VERSION;
 
+/** @api */
 class BodyParsingMiddleware implements MiddlewareInterface
 {
     /**

Slim/Middleware/ContentLengthMiddleware.php

@@ -15,6 +15,7 @@
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
+/** @api */
 class ContentLengthMiddleware implements MiddlewareInterface
 {
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Slim/Middleware/ErrorMiddleware.php

@@ -25,6 +25,7 @@
 use function get_class;
 use function is_subclass_of;
 
+/** @api */
 class ErrorMiddleware implements MiddlewareInterface
 {
     protected CallableResolverInterface $callableResolver;

Slim/Middleware/MethodOverrideMiddleware.php

@@ -18,6 +18,7 @@
 use function is_array;
 use function strtoupper;
 
+/** @api */
 class MethodOverrideMiddleware implements MiddlewareInterface
 {
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Slim/Middleware/OutputBufferingMiddleware.php

@@ -23,6 +23,7 @@
 use function ob_get_clean;
 use function ob_start;
 
+/** @api */
 class OutputBufferingMiddleware implements MiddlewareInterface
 {
     public const APPEND = 'append';

Slim/MiddlewareDispatcher.php

@@ -28,6 +28,10 @@
 use function preg_match;
 use function sprintf;
 
+/**
+ * @api
+ * @template TContainerInterface of (ContainerInterface|null)
+ */
 class MiddlewareDispatcher implements MiddlewareDispatcherInterface
 {
     /**
@@ -37,8 +41,12 @@ class MiddlewareDispatcher implements MiddlewareDispatcherInterface
 
     protected ?CallableResolverInterface $callableResolver;
 
+    /** @var TContainerInterface $container */
     protected ?ContainerInterface $container;
 
+    /**
+     * @param TContainerInterface $container
+     */
     public function __construct(
         RequestHandlerInterface $kernel,
         ?CallableResolverInterface $callableResolver = null,
@@ -131,6 +139,7 @@ public function handle(ServerRequestInterface $request): ResponseInterface
      * Middleware are organized as a stack. That means middleware
      * that have been added before will be executed after the newly
      * added one (last in, first out).
+     * @return MiddlewareDispatcher<TContainerInterface>
      */
     public function addDeferred(string $middleware): self
     {
@@ -183,6 +192,7 @@ public function handle(ServerRequestInterface $request): ResponseInterface
                     $instance = null;
                     $method = null;
 
+                    /** @psalm-suppress ArgumentTypeCoercion */
                     // Check for Slim callable as `class:method`
                     if (preg_match(CallableResolver::$callablePattern, $resolved, $matches)) {
                         $resolved = $matches[1];
@@ -237,6 +247,7 @@ public function handle(ServerRequestInterface $request): ResponseInterface
      * Middleware are organized as a stack. That means middleware
      * that have been added before will be executed after the newly
      * added one (last in, first out).
+     * @return MiddlewareDispatcher<TContainerInterface>
      */
     public function addCallable(callable $middleware): self
     {