Neos Flow Middleware Tutorial: understanding and applying PSR-15

What is a Middleware?

Why is it important for Neos Flow?

How middlewares works in Neos Flow

Quelle: Flow Framework > HTTP Foundation

 

In simple terms, the diagram can be summarized as follows: The browser sends a request to the server. There, a suitable RequestHandler takes over and creates a PSR-7 request object from the request. This object contains all relevant information from the original HTTP request and is then routed through the middleware chain implemented according to PSR-15.

 

PSR-7 defines standardized PHP interfaces for HTTP messages, i.e., for requests, responses, streams, URIs, and uploaded files. This provides a common, framework-independent basis for working with HTTP objects. The objects are immutable, which means that any change creates a new instance, thus guaranteeing consistent behavior.

 

PSR-15 builds on these PSR-7 interfaces and defines how middleware and request handlers look in the server context. A middleware receives a PSR-7 request object and decides whether to return a response itself or forward the request to the next handler. This creates a clearly defined and compatible middleware chain that works independently of the framework used.

How do you implement middleware in Neos Flow?

<?php

namespace Vendor\Package\Http;

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

// A sample HTTP middleware that adds a custom header to the response
final class SomeMiddleware implements MiddlewareInterface
{
	public function process (ServerRequestInterface $request, RequestHandlerInterface $next): ResponseInterface {
		$response = $next->handle($request);
		return $response->withAddedHeader ('X-MyHeader', '123');
	}
}

Neos:
  Flow:
    http:
      middlewares:
        'custom':
          position: 'before dispatch'
          middleware: 'Vendor\Package\Http\SomeMiddleware'

$ ./flow middleware:list
Currently configured middlewares:
+----+---------------------+-----------------------------------------------------------------+
| #  | Name                | Class name                                                      |
+----+---------------------+-----------------------------------------------------------------+
| 1  | standardsCompliance | Neos\Flow\Http\Middleware\StandardsComplianceMiddleware         |
| 2  | trustedProxies      | Neos\Flow\Http\Middleware\TrustedProxiesMiddleware              |
| 3  | methodOverride      | Neos\Flow\Http\Middleware\MethodOverrideMiddleware              |
| 4  | session             | Neos\Flow\Http\Middleware\SessionMiddleware                     |
| 5  | ajaxWidget          | Neos\FluidAdaptor\Core\Widget\AjaxWidgetMiddleware              |
| 6  | detectSite          | Neos\Neos\FrontendRouting\SiteDetection\SiteDetectionMiddleware |
| 7  | routing             | Neos\Flow\Mvc\Routing\RoutingMiddleware                         |
| 8  | poweredByHeader     | Neos\Flow\Http\Middleware\PoweredByMiddleware                   |
| 9  | flashMessages       | Neos\Flow\Mvc\FlashMessage\FlashMessageMiddleware               |
| 10 | parseBody           | Neos\Flow\Http\Middleware\RequestBodyParsingMiddleware          |
| 11 | securityEntryPoint  | Neos\Flow\Http\Middleware\SecurityEntryPointMiddleware          |
| 12 | dispatch            | Neos\Flow\Mvc\DispatchMiddleware                                |
+----+---------------------+-----------------------------------------------------------------+

Practical Examples

Logging middleware for certain Flow contexts

<?php

namespace Vendor\Package\Http;

use Neos\Flow\Annotations as Flow;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Log\LoggerInterface;

// A middleware that logs all requests if they are in development context
class LoggingMiddleware implements MiddlewareInterface
{
	#[Flow\Inject] protected LoggerInterface $logger;

	#[Flow\InjectConfiguration(path: "core. context", package: "Neos.Flow", type: "Settings")]
	protected string $context = "Development";

	public function process (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
	{
		if ($this->context== "Development/Docker") {
			$this->logger->info("Incoming request: Method -> " . $request->getMethod() . "; Query -> " . $request->getUri()->getQuery());
		}

		return $response = $handler->handle($request);
	}
}

Maintenance mode middleware

<?php

namespace Vendor\Package\Http;

use Neos\Flow\Annotations as Flow;
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 Vendor\Package\Http\MaintenanceResponse;

// A middleware that creates a maintenance response if in maintenance mode and not permitted user
class MaintenanceMiddleware implements MiddlewareInterface
{
	#[Flow\InjectConfiguration(path: "core.maintenanceActive", package: "Vendor.Package", type: "Settings")]
	protected bool $isMaintenanceActive = false;

	public function process (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
	{
		$clientIp = $request->getServerParams()['REMOTE_ADDR'] ?? '';

		if (!$this->isMaintenanceActive || $clientIp === "123.123.123.123") {
			return $handler->handle($request);
		}

		return new MaintenanceResponse();
	}
}

Related links