Mezzio: a PSR-15 middleware framework for PHP

It relies only on the Mezzio documentation landing page supplied as the source packet, and that page is short. Where it says nothing, this guide says unknown.

What Mezzio is

Mezzio is a framework. It is not a standalone PHP runtime, and it is not a CMS. The documentation describes it as PSR-7 middleware in minutes, and the page title mentions PSR-15 middleware. Your application is built from middleware and request handlers that take an HTTP request and produce an HTTP response.

Keep three distinctions straight:

• PHP core is not Mezzio. PHP supplies the language and its extensions. Mezzio is Composer-distributed userland code running on top of it.
• Framework components are not CMS products. Mezzio and its add-on packages are building blocks for your own application. A CMS such as Drupal is a complete content product with its own content model. Mezzio does not ship one, and the source describes none.
• Adapters are not runtimes. The packet lists mezzio/mezzio-swoole, described as support of Swoole in a Mezzio application. That is an integration layer. The Swoole extension supplies the server, and Mezzio does not become a runtime itself.

Architecture: a core plus many packages

The packet shows a family of separate packages, grouped by purpose:

• Core and integration: mezzio/mezzio, mezzio/mezzio-valinor (converts PSR-7 requests to well-typed data structures) and mezzio/mezzio-swoole.
• API: mezzio/mezzio-hal (Hypertext Application Language for PSR-7) and mezzio/mezzio-problem-details (problem details for HTTP API responses and middleware).
• Authentication: mezzio-authentication, with adapters for HTTP Basic, session-backed username and password, laminas-authentication, and OAuth2 server middleware.
• Authorization: mezzio-authorization, with ACL and RBAC adapters, plus mezzio-cors for project- or route-specific CORS configuration.
• Session: mezzio-csrf, mezzio-flash, mezzio-session, and session persistence via PSR-6 cache item pools or ext-session.

You add only the packages you need. The packet does not say how they are wired together or which are installed by default, so read each package page for that.

Execution model

The packet does not state a request lifecycle, so the following is general PHP knowledge and not a claim about Mezzio internals.

In the classic model, a web server hands each request to a PHP process or worker. Application objects are built, the response is produced, and request state is discarded. A mistake in global or static state mostly stays inside one request.

A persistent worker keeps the PHP process, and therefore loaded code and objects, alive across many requests. The Swoole adapter exists in the Mezzio family, so this model is relevant. Whether the adapter's workers reuse the container, and which services are reset between requests, is unknown from the supplied source.

Persistent workers can leak state. Typical sources are:

• static properties and singletons;
• service-container objects that cache request data;
• session containers, authenticated user objects, CSRF tokens and flash messages;
• open connections, buffers and caches.

If one request's identity or session data survives into the next, the result is a security fault, not just a bug. Defensive habits:

• Keep services stateless.
• Pass request data through the PSR-7 request and its attributes, not through globals.
• Create or reset per-request objects explicitly.
• Test with several consecutive requests from different users.

The source does not describe the adapter's own cleanup behaviour, so do not assume any.

Note that Swoole and Open Swoole are different projects. The packet mentions only Swoole. Whether the adapter works with Open Swoole is unknown.

Practical use cases

The package list points to HTTP-centred applications:

• JSON APIs, using HAL and problem-details responses.
• Applications with session login, using the session and authentication packages.
• Services with OAuth2, role-based or ACL-based access control and CORS rules.
• Handlers that map requests to typed data via the Valinor integration.

The source gives no benchmarks, so this guide makes no speed claims.

Installation approach

The packet names the Composer packages but does not show an installation command or a project template. The right approach is to follow the official documentation for the core package and for each add-on. Do not assemble a stand-alone Mezzio application from memory. Composer, network access and a PHP CLI are needed.

The learning track targets PHP 8.4, with PHP 8.5 planned. Mezzio's supported PHP versions, current version, licence and lifecycle status are not in the supplied source, so they are unknown. Check the package metadata before committing to a PHP version.

The example

The example is deliberately small. It is not a full Mezzio application. It shows the unit Mezzio is organised around, a PSR-15 request handler, and runs it from a CLI script with a Diactoros request. It is not a browser exercise and needs Composer and network access. How to register the handler with Mezzio's routing is not covered by the packet, so that step is left to the official docs.

Strengths

• It is built on PSR-7 and PSR-15 abstractions, so handlers stay small and separate from any particular server.
• It has a modular package set covering APIs, authentication, authorization and sessions.
• It has an adapter for Swoole.

Limitations

• The supplied source is a landing page, so lifecycle, compatibility, licence and deployment details are unknown.
• A framework is not a CMS, so you build content management yourself or choose a different product.
• Persistent workers raise state-leakage risks that classic request handling mostly hides.
• The Swoole adapter's cleanup guarantees are undocumented in the packet.

Deployment

The packet contains no deployment instructions. Classic web-server hosting and the Swoole adapter are different deployment shapes, and both need guidance from the official docs. If you ever expose a development server, bind it to 127.0.0.1 and never expose FastCGI publicly.

Links

Use the official documentation at docs.mezzio.dev for everything beyond this overview.

{
  "require": {
    "psr/http-server-handler": "*",
    "laminas/laminas-diactoros": "*"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

<?php

declare(strict_types=1);

namespace App;

use Laminas\Diactoros\Response\TextResponse;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

final class HelloHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $params = $request->getQueryParams();
        $name = isset($params['name']) && is_string($params['name'])
            ? trim($params['name'])
            : '';

        if ($name === '') {
            $name = 'world';
        }

        return new TextResponse('Hello, ' . $name . '!');
    }
}

<?php

declare(strict_types=1);

use App\HelloHandler;
use Laminas\Diactoros\ServerRequest;

require __DIR__ . '/../vendor/autoload.php';

$request = (new ServerRequest([], [], '/hello', 'GET'))
    ->withQueryParams(['name' => 'PHP']);

$response = (new HelloHandler())->handle($request);

echo $response->getStatusCode(), PHP_EOL;
echo (string) $response->getBody(), PHP_EOL;

composer install
php bin/run.php