Middleware (Slim\Middleware)

The Slim\Middleware namespace provides Slim 4's six built-in PSR-15 (Psr\Http\Server\MiddlewareInterface) components: RoutingMiddleware, ErrorMiddleware, BodyParsingMiddleware, ContentLengthMiddleware, MethodOverrideMiddleware, and OutputBufferingMiddleware. Because Slim's MiddlewareDispatcher wraps middleware in a concentric LIFO (Last-In, First-Out) onion stack, the middleware added last executes first on inbound requests.

from drawlib.canvas import save, setup
from drawlib.lines import line
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=180, height=82)

# Outer frame label
text(
    (90, 75),
    "Inbound ServerRequestInterface  --->  Concentric PSR-15 Middleware Stack  --->  RouteRunner",
    style=Styles.PrimaryBold.patch(text_size=11.5),
)

# Top Row (Outer to Mid-Layer)
rectangle(
    (31, 53),
    width=46,
    height=18,
    style=Styles.AccentFlat.patch(shape_r=2.5),
)
text((31, 57.5), "1. ErrorMiddleware", style=Styles.WhiteBold.patch(text_size=11.0))
text((31, 52.0), "Outermost try / catch", style=Styles.White.patch(text_size=10.0))
text((31, 47.0), "Added LAST (app->add)", style=Styles.White.patch(text_size=9.5))

rectangle(
    (90, 53),
    width=46,
    height=18,
    style=Styles.Neutral.patch(shape_r=2.5),
)
text((90, 57.5), "2. ContentLength", style=Styles.BlackBold.patch(text_size=11.0))
text((90, 52.0), "& OutputBuffering", style=Styles.Dark.patch(text_size=10.0))
text((90, 47.0), "Stream capture & size", style=Styles.Dark.patch(text_size=9.5))

rectangle(
    (149, 53),
    width=46,
    height=18,
    style=Styles.PrimaryNeutral.patch(shape_r=2.5),
)
text((149, 57.5), "3. BodyParsing", style=Styles.BlackBold.patch(text_size=11.0))
text((149, 52.0), "JSON / XML / Form", style=Styles.Dark.patch(text_size=10.0))
text((149, 47.0), "withParsedBody()", style=Styles.Dark.patch(text_size=9.5))

# Bottom Row (Inner Layers to Kernel)
rectangle(
    (149, 20),
    width=46,
    height=18,
    style=Styles.SecondaryNeutral.patch(shape_r=2.5),
)
text((149, 24.5), "4. MethodOverride", style=Styles.BlackBold.patch(text_size=11.0))
text((149, 19.0), "Header or POST _METHOD", style=Styles.Dark.patch(text_size=10.0))
text((149, 14.0), "withMethod()", style=Styles.Dark.patch(text_size=9.5))

rectangle(
    (90, 20),
    width=46,
    height=18,
    style=Styles.PrimaryFlat.patch(shape_r=2.5),
)
text((90, 24.5), "5. RoutingMiddleware", style=Styles.WhiteBold.patch(text_size=11.0))
text((90, 19.0), "FastRoute match", style=Styles.White.patch(text_size=10.0))
text((90, 14.0), "Sets RouteContext", style=Styles.White.patch(text_size=9.5))

rectangle(
    (31, 20),
    width=46,
    height=18,
    style=Styles.Neutral.patch(shape_r=2.5),
)
text((31, 24.5), "6. RouteRunner", style=Styles.BlackBold.patch(text_size=11.0))
text((31, 19.0), "Group & Route MW", style=Styles.Dark.patch(text_size=10.0))
text((31, 14.0), "Route::run(request)", style=Styles.Dark.patch(text_size=9.5))

# Arrows connecting 1 -> 2 -> 3 -> 4 -> 5 -> 6
line((54, 53), (67, 53), arrow_head="->", style=Styles.PrimaryBold)
line((113, 53), (126, 53), arrow_head="->", style=Styles.PrimaryBold)
line((149, 44), (149, 29), arrow_head="->", style=Styles.PrimaryBold)
line((126, 20), (113, 20), arrow_head="->", style=Styles.PrimaryBold)
line((67, 20), (54, 20), arrow_head="->", style=Styles.PrimaryBold)

save()

classSlim\Middleware\RoutingMiddleware#

• Source: Slim/Middleware/RoutingMiddleware.php
• Namespace: Slim\Middleware
• Implements: Psr\Http\Server\MiddlewareInterface

RoutingMiddleware executes FastRoute URI and HTTP method matching via RouteResolverInterface before downstream middleware or RouteRunner is reached. It populates RouteContext::ROUTE_PARSER, RouteContext::ROUTING_RESULTS, and RouteContext::ROUTE on the ServerRequestInterface, and throws HttpNotFoundException or HttpMethodNotAllowedException when routing fails.

Class Signature#

<?php

declare(strict_types=1);

namespace Slim\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use RuntimeException;
use Slim\Exception\HttpMethodNotAllowedException;
use Slim\Exception\HttpNotFoundException;
use Slim\Interfaces\RouteParserInterface;
use Slim\Interfaces\RouteResolverInterface;
use Slim\Routing\RoutingResults;

class RoutingMiddleware implements MiddlewareInterface
{
    protected RouteResolverInterface $routeResolver;
    protected RouteParserInterface $routeParser;

    public function __construct(
        RouteResolverInterface $routeResolver,
        RouteParserInterface $routeParser
    );

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;

    public function performRouting(ServerRequestInterface $request): ServerRequestInterface;

    protected function resolveRoutingResultsFromRequest(
        ServerRequestInterface $request
    ): RoutingResults;
}

Properties#

Methods & Parameters#

Usage Example#

use Slim\Factory\AppFactory;

$app = AppFactory::create();

// Register RoutingMiddleware via the App helper before ErrorMiddleware:
$app->addRoutingMiddleware();

// Any middleware added BEFORE addRoutingMiddleware() (i.e. inner to it) can read RouteContext:
$app->addErrorMiddleware(true, true, true);

classSlim\Middleware\ErrorMiddleware#

• Source: Slim/Middleware/ErrorMiddleware.php
• Namespace: Slim\Middleware
• Implements: Psr\Http\Server\MiddlewareInterface

ErrorMiddleware wraps downstream request execution in a try / catch (Throwable $e) block and delegates caught exceptions or PHP errors to a mapped ErrorHandlerInterface or custom error handler callable. When catching an HttpException, it extracts the most recent ServerRequestInterface via $exception->getRequest() so routing attributes added inside the pipeline remain available to error renderers.

Class Signature#

<?php

declare(strict_types=1);

namespace Slim\Middleware;

use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Log\LoggerInterface;
use Slim\Handlers\ErrorHandler;
use Slim\Interfaces\CallableResolverInterface;
use Slim\Interfaces\ErrorHandlerInterface;
use Throwable;

/** @api */
class ErrorMiddleware implements MiddlewareInterface
{
    protected CallableResolverInterface $callableResolver;
    protected ResponseFactoryInterface $responseFactory;
    protected bool $displayErrorDetails;
    protected bool $logErrors;
    protected bool $logErrorDetails;
    protected ?LoggerInterface $logger = null;
    protected array $handlers = [];
    protected array $subClassHandlers = [];
    protected $defaultErrorHandler;

    public function __construct(
        CallableResolverInterface $callableResolver,
        ResponseFactoryInterface $responseFactory,
        bool $displayErrorDetails,
        bool $logErrors,
        bool $logErrorDetails,
        ?LoggerInterface $logger = null
    );

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;

    public function handleException(
        ServerRequestInterface $request,
        Throwable $exception
    ): ResponseInterface;

    public function getErrorHandler(string $type);
    public function getDefaultErrorHandler();
    public function setDefaultErrorHandler($handler): self;
    public function setErrorHandler(
        $typeOrTypes,
        $handler,
        bool $handleSubclasses = false
    ): self;
}

Properties#

Methods & Parameters#

Usage Example#

use DomainException;
use Slim\Exception\HttpNotFoundException;
use Slim\Factory\AppFactory;

$app = AppFactory::create();
$errorMiddleware = $app->addErrorMiddleware(false, true, true, $logger);

// Register a custom handler for DomainException and all its subclasses
$errorMiddleware->setErrorHandler(
    DomainException::class,
    CustomDomainErrorHandler::class,
    true
);

// Customize the default ErrorHandler (e.g. force JSON output)
$defaultHandler = $errorMiddleware->getDefaultErrorHandler();
$defaultHandler->forceContentType('application/json');

classSlim\Middleware\BodyParsingMiddleware#

• Source: Slim/Middleware/BodyParsingMiddleware.php
• Namespace: Slim\Middleware
• Implements: Psr\Http\Server\MiddlewareInterface

BodyParsingMiddleware inspects the inbound request's Content-Type header when $request->getParsedBody() is empty, parses the raw request body stream using a media-type parser registry, and returns a new request instance via $request->withParsedBody($parsedBody). Out of the box, it registers parsers for application/json, application/x-www-form-urlencoded, application/xml, and text/xml, and automatically resolves RFC 6839 structured syntax suffixes (+json, +xml).

from drawlib.canvas import save, setup
from drawlib.lines import line
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=180, height=84)

# Left Panel: ErrorMiddleware
rectangle(
    (46, 42),
    width=80,
    height=74,
    style=Styles.Neutral.patch(shape_r=3.0),
)
text((46, 73.5), "ErrorMiddleware::getErrorHandler()", style=Styles.PrimaryBold.patch(text_size=11.5))

rectangle(
    (46, 59),
    width=66,
    height=12,
    style=Styles.PrimaryFlat.patch(shape_r=2.0),
)
text((46, 61.5), "1. Exact Class Match", style=Styles.WhiteBold.patch(text_size=11.0))
text((46, 56.5), "handlers[type] direct lookup", style=Styles.White.patch(text_size=10.0))

rectangle(
    (46, 40),
    width=66,
    height=12,
    style=Styles.PrimaryNeutral.patch(shape_r=2.0),
)
text((46, 42.5), "2. Subclass Match", style=Styles.BlackBold.patch(text_size=11.0))
text((46, 37.5), "is_subclass_of(type, class)", style=Styles.Dark.patch(text_size=10.0))

rectangle(
    (46, 21),
    width=66,
    height=12,
    style=Styles.SecondaryNeutral.patch(shape_r=2.0),
)
text((46, 23.5), "3. Default ErrorHandler", style=Styles.BlackBold.patch(text_size=11.0))
text((46, 18.5), "getDefaultErrorHandler()", style=Styles.Dark.patch(text_size=10.0))

line((46, 53), (46, 46), arrow_head="->", style=Styles.PrimaryBold)
line((46, 34), (46, 27), arrow_head="->", style=Styles.PrimaryBold)

# Right Panel: BodyParsingMiddleware
rectangle(
    (134, 42),
    width=80,
    height=74,
    style=Styles.PrimaryNeutral.patch(shape_r=3.0),
)
text((134, 73.5), "BodyParsingMiddleware::parseBody()", style=Styles.PrimaryBold.patch(text_size=11.5))

rectangle(
    (134, 59),
    width=66,
    height=12,
    style=Styles.AccentFlat.patch(shape_r=2.0),
)
text((134, 61.5), "1. Exact Media Type", style=Styles.WhiteBold.patch(text_size=11.0))
text((134, 56.5), "json / form-urlencoded / xml", style=Styles.White.patch(text_size=10.0))

rectangle(
    (134, 40),
    width=66,
    height=12,
    style=Styles.SecondaryNeutral.patch(shape_r=2.0),
)
text((134, 42.5), "2. RFC 6839 +Suffix Fallback", style=Styles.BlackBold.patch(text_size=11.0))
text((134, 37.5), "vnd.api+json -> application/json", style=Styles.Dark.patch(text_size=9.5))

rectangle(
    (134, 21),
    width=66,
    height=12,
    style=Styles.Neutral.patch(shape_r=2.0),
)
text((134, 23.5), "3. Validate & Attach", style=Styles.BlackBold.patch(text_size=11.0))
text((134, 18.5), "array | object | null -> Request", style=Styles.Dark.patch(text_size=10.0))

line((134, 53), (134, 46), arrow_head="->", style=Styles.PrimaryBold)
line((134, 34), (134, 27), arrow_head="->", style=Styles.PrimaryBold)

save()

Class Signature#

<?php

declare(strict_types=1);

namespace Slim\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use RuntimeException;

/** @api */
class BodyParsingMiddleware implements MiddlewareInterface
{
    /** @var callable[] */
    protected array $bodyParsers;

    /**
     * @param callable[] $bodyParsers
     */
    public function __construct(array $bodyParsers = []);

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;

    public function registerBodyParser(string $mediaType, callable $callable): self;
    public function hasBodyParser(string $mediaType): bool;
    public function getBodyParser(string $mediaType): callable;

    protected function registerDefaultBodyParsers(): void;
    protected function parseBody(ServerRequestInterface $request);
    protected function getMediaType(ServerRequestInterface $request): ?string;
    protected static function disableXmlEntityLoader(bool $disable): bool;
}

Properties & Default Parsers#

Methods & Parameters#

Usage Example#

use Slim\Factory\AppFactory;

$app = AppFactory::create();

// Register BodyParsingMiddleware via the App helper:
$bodyParsingMiddleware = $app->addBodyParsingMiddleware();

// Add a custom YAML body parser:
$bodyParsingMiddleware->registerBodyParser('application/x-yaml', function (string $input) {
    $parsed = yaml_parse($input);
    return is_array($parsed) ? $parsed : null;
});

classSlim\Middleware\ContentLengthMiddleware#

• Source: Slim/Middleware/ContentLengthMiddleware.php
• Namespace: Slim\Middleware
• Implements: Psr\Http\Server\MiddlewareInterface

ContentLengthMiddleware is an outbound post-processing middleware that inspects the ResponseInterface returned by $handler->handle($request) and automatically attaches a Content-Length header if $response->getBody()->getSize() is non-null and no Content-Length header is already present.

Class Signature#

<?php

declare(strict_types=1);

namespace Slim\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

/** @api */
class ContentLengthMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

Methods & Parameters#

Usage Example#

use Slim\Factory\AppFactory;
use Slim\Middleware\ContentLengthMiddleware;

$app = AppFactory::create();

// Add near the outside of the middleware stack so all responses receive Content-Length:
$app->add(new ContentLengthMiddleware());

classSlim\Middleware\MethodOverrideMiddleware#

• Source: Slim/Middleware/MethodOverrideMiddleware.php
• Namespace: Slim\Middleware
• Implements: Psr\Http\Server\MiddlewareInterface

MethodOverrideMiddleware allows HTML forms and restricted HTTP clients to tunnel PUT, PATCH, or DELETE requests over POST or custom headers. It checks the X-Http-Method-Override request header first; if absent and the request method is POST, it checks $request->getParsedBody()['_METHOD'] and rewinds the request body stream if EOF was reached.

[!IMPORTANT] When using the POST body _METHOD parameter with application/x-www-form-urlencoded or application/json payloads, BodyParsingMiddleware must execute before MethodOverrideMiddleware, and MethodOverrideMiddleware must execute before RoutingMiddleware. Because Slim's middleware stack is LIFO, register them in reverse order: addRoutingMiddleware(), then add(MethodOverrideMiddleware), then addBodyParsingMiddleware().

Class Signature#

<?php

declare(strict_types=1);

namespace Slim\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

/** @api */
class MethodOverrideMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

Methods & Parameters#

Usage Example#

use Slim\Factory\AppFactory;
use Slim\Middleware\MethodOverrideMiddleware;

$app = AppFactory::create();

// LIFO registration order:
// 1. RoutingMiddleware runs 3rd (uses overridden method)
$app->addRoutingMiddleware();

// 2. MethodOverrideMiddleware runs 2nd (reads parsed body _METHOD or header)
$app->add(new MethodOverrideMiddleware());

// 3. BodyParsingMiddleware runs 1st (parses POST body)
$app->addBodyParsingMiddleware();

classSlim\Middleware\OutputBufferingMiddleware#

• Source: Slim/Middleware/OutputBufferingMiddleware.php
• Namespace: Slim\Middleware
• Implements: Psr\Http\Server\MiddlewareInterface

OutputBufferingMiddleware captures any stray PHP output (echo, print, var_dump) emitted during downstream middleware and route execution using ob_start() and ob_get_clean(), and either appends or prepends the captured buffer to the PSR-7 ResponseInterface body. If an exception is thrown downstream, it safely cleans the buffer with ob_end_clean() before rethrowing.

Class Signature#

<?php

declare(strict_types=1);

namespace Slim\Middleware;

use InvalidArgumentException;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Throwable;

/** @api */
class OutputBufferingMiddleware implements MiddlewareInterface
{
    public const APPEND = 'append';
    public const PREPEND = 'prepend';

    protected StreamFactoryInterface $streamFactory;
    protected string $style;

    public function __construct(
        StreamFactoryInterface $streamFactory,
        string $style = 'append'
    );

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

Constants & Properties#

Methods & Parameters#

Usage Example#

use Slim\Factory\AppFactory;
use Slim\Middleware\OutputBufferingMiddleware;
use Slim\Psr7\Factory\StreamFactory;

$app = AppFactory::create();

$streamFactory = new StreamFactory();
$app->add(new OutputBufferingMiddleware($streamFactory, OutputBufferingMiddleware::APPEND));