Getting Started

Quick Start: Standalone Usage

Mezzio allows you to get started at your own pace. You can start with the simplest example, detailed below, or move on to a more structured, configuration-driven approach as detailed in the use case examples.

Deprecated with version 2.2

The Mezzio\AppFactory detailed in this chapter is deprecated as of version 2.2, and will be removed in version 3.0. We recommend instead constructing Mezzio\Application manually, or using a Laminas\Stratigility\MiddlewarePipe instance instead.

1. Create a new project directory

First, let's create a new project directory and enter it:

$ mkdir mezzio
$ cd mezzio

2. Install Mezzio

If you haven't already, install Composer. Once you have, we can install Mezzio, along with a router and a container:

$ composer require mezzio/mezzio mezzio/mezzio-fastroute laminas/laminas-servicemanager


Mezzio needs a routing implementation in order to create routed middleware. We suggest FastRoute in the quick start, but you can also currently choose from Aura.Router and laminas-router.


We highly recommend using dependency injection containers with Mezzio; they allow you to define dependencies for your middleware, as well as to lazy load your middleware only when it needs to be executed. We suggest laminas-servicemanager in the quick start, but you can also use any container supporting PSR-11 Container.

3. Create a web root directory

You'll need a directory from which to serve your application, and for security reasons, it's a good idea to keep it separate from your source code. We'll create a public/ directory for this:

$ mkdir public

4. Create your bootstrap script

Next, we'll create a bootstrap script. Such scripts typically set up the environment, set up the application, and invoke it. This needs to be in our web root, and we want it to intercept any incoming request; as such, we'll use public/index.php:


use Interop\Http\ServerMiddleware\DelegateInterface;
use Laminas\Diactoros\Response\TextResponse;
use Mezzio\AppFactory;

require 'vendor/autoload.php';

$app = AppFactory::create();

$app->get('/', function ($request, DelegateInterface $delegate) {
    return new TextResponse('Hello, world!');


Rewriting URLs

Many web servers will not rewrite URLs to the bootstrap script by default. If you use Apache, for instance, you'll need to set up rewrite rules to ensure your bootstrap is invoked for unknown URLs. We'll cover that in a later chapter.

Routing and dispatching

Note the lines from the above:


Mezzio's Application class provides two separate middlewares, one for routing, and one for dispatching middleware matched by routing. This allows you to slip in validations between the two activities if desired. They are not automatically piped to the application, however, to allow exactly that situation, which means they must be piped manually.

5. Start a web server

Since we're just testing out the basic functionality of our application, we'll use PHP's built-in web server.

From the project root directory, execute the following:

$ php -S -t public/

This starts up a web server on localhost port 8080; browse to http://localhost:8080/ to see if your application responds correctly!

Tip: Serve via Composer

To simplify starting up a local web server, try adding the following to your composer.json:

"scripts": {
    "serve": "php -S -t public/"

Once you've added that, you can fire up the web server using:

$ composer serve

Setting a timeout

Composer commands time out after 300 seconds (5 minutes). On Linux-based systems, the php -S command that composer serve spawns continues running as a background process, but on other systems halts when the timeout occurs.

As such, we recommend running the serve script using a timeout. This can be done by using composer run to execute the serve script, with a --timeout option. When set to 0, as in the previous example, no timeout will be used, and it will run until you cancel the process (usually via Ctrl-C). Alternately, you can specify a finite timeout; as an example, the following will extend the timeout to a full day:

$ composer run --timeout=86400 serve

Next steps

At this point, you have a working mezzio application, that responds to a single route. From here, you may want to read up on:

Additionally, we have more use case examples.