PHPackages                             middlewares/request-handler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. middlewares/request-handler

ActiveLibrary[HTTP & Networking](/categories/http)

middlewares/request-handler
===========================

Middleware to execute request handlers

v2.1.0(1y ago)451.6M↓18.5%620MITPHPPHP ^7.2 || ^8.0CI passing

Since Apr 19Pushed 11mo ago6 watchersCompare

[ Source](https://github.com/middlewares/request-handler)[ Packagist](https://packagist.org/packages/middlewares/request-handler)[ Docs](https://github.com/middlewares/request-handler)[ RSS](/packages/middlewares-request-handler/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (9)Versions (17)Used By (20)

middlewares/request-handler
===========================

[](#middlewaresrequest-handler)

[![Latest Version on Packagist](https://camo.githubusercontent.com/062a03c6c3c5c7f04db3dc41e42fb0ca9a7be0dd2448a6cccf347b9183a965b3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6964646c6577617265732f726571756573742d68616e646c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/middlewares/request-handler)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Testing](https://github.com/middlewares/request-handler/workflows/testing/badge.svg)](https://github.com/middlewares/request-handler/workflows/testing/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/04951e3ad1112545062cf51a49e7c809ee7dcf8998bb85a19a6efc9726f664af/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6964646c6577617265732f726571756573742d68616e646c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/middlewares/request-handler)

Middleware to execute request handlers discovered by a router.

Requirements
------------

[](#requirements)

- PHP >= 7.2
- A [PSR-7 http library](https://github.com/middlewares/awesome-psr15-middlewares#psr-7-implementations)
- A [PSR-15 middleware dispatcher](https://github.com/middlewares/awesome-psr15-middlewares#dispatcher)
- Optionally, a [PSR-11](https://github.com/php-fig/container) container to resolve the route handlers

Installation
------------

[](#installation)

This package is installable and autoloadable via Composer as [middlewares/request-handler](https://packagist.org/packages/middlewares/request-handler).

```
composer require middlewares/request-handler
```

You may also want to install any route middleware like [middlewares/fast-route](https://packagist.org/packages/middlewares/fast-route) or [middlewares/aura-router](https://packagist.org/packages/middlewares/aura-router) for routing.

Purpose
-------

[](#purpose)

There are two completely separate steps when it comes to route handling:

1. Determining if the request is valid and can be resolved by the application.
2. Handling the request inside the application.

The first step usually resolves into a route callback, while the product of the second one is usually the result of executing that callback.

Multiple things that can happen between the first and second steps: input validation, authentication, authorization, etc. and in some scenarios we may not want to continue processing the request (e.g. auth, accessing DB resources, etc.) if that would ultimately fail to resolve e.g. procuding an *HTTP 400* error.

Splitting routing from request handling allows us to use any middleware between these two steps. It also makes the `request-handler` middleware able to be used with any routing component.

Example
-------

[](#example)

A routing middleware needs to be called before the request can be handled. In this example, we will use `fast-route` middleware.

```
// Create the routing dispatcher
$fastRouteDispatcher = FastRoute\simpleDispatcher(function (FastRoute\RouteCollector $r) {
    $r->get('/hello/{name}', HelloWorldController::class);
});

$dispatcher = new Dispatcher([
    new Middlewares\FastRoute($fastRouteDispatcher),
    // ...
    new Middlewares\RequestHandler(),
]);

$response = $dispatcher->dispatch(new ServerRequest('/hello/world'));
```

When the request handler is invoked, it expects a request attribute to be defined that contains a reference to the handler. The handler must be a string, a callable or an object implementing `MiddlewareInterface` or `RequestHandlerInterface`. If it's a string, a `ContainerInterface` will be used to resolve it and get the `MiddlewareInterface` or `RequestHandlerInterface` to use. If it's a callable, it will be converted automatically to `MiddlewareInterface` using the [`Middlewares\Utils\CallableHandler`](https://github.com/middlewares/utils#callablehandler)

```
// Use a PSR-11 container to create the instances of the request handlers
$container = new RequestHandlerContainer();

$dispatcher = new Dispatcher([
    // ...
    new Middlewares\RequestHandler($container),
]);
```

Usage
-----

[](#usage)

Define the container used to resolve the handlers if they are provided as string (or an array with 2 strings). By default will use [`Middlewares\Utils\RequestHandlerContainer`](https://github.com/middlewares/utils/blob/master/src/RequestHandlerContainer.php).

```
// Use the default PSR-11 container to create the intances of the request handlers
$handler = new Middlewares\RequestHandler();

// Use a custom PSR-11 container
$container = new RequestHandlerContainer();

$handler = new Middlewares\RequestHandler($container);
```

### handlerAttribute

[](#handlerattribute)

Configures the attribute name used to get the handler reference in the server request. The default is `request-handler`.

```
Dispatcher::run([
    (new Middlewares\RequestHandler())->handlerAttribute('route'),
]);
```

### continueOnEmpty

[](#continueonempty)

If the server request attribute is empty or does not exists, an exception is throwed. This function changes this behavior to continue with the next middleware.

```
Dispatcher::run([
    //Try this, and if it's empty, continue
    (new Middlewares\RequestHandler())->continueOnEmpty(),

    //So we can try that
    (new Middlewares\RequestHandler())->handlerAttribute('other'),
]);
```

---

Please see [CHANGELOG](CHANGELOG.md) for more information about recent changes and [CONTRIBUTING](CONTRIBUTING.md) for contributing details.

The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance48

Moderate activity, may be stable

Popularity52

Moderate usage in the ecosystem

Community33

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 77.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~193 days

Recently: every ~485 days

Total

16

Last Release

421d ago

Major Versions

v0.5.0 → v1.0.02018-01-24

v1.4.0 → v2.0.02019-11-29

PHP version history (4 changes)v0.1.0PHP ^5.6 || ^7.0

v0.4.0PHP ^7.0

v2.0.0PHP ^7.2

v2.0.1PHP ^7.2 || ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/38203?v=4)[Woody Gilk](/maintainers/shadowhand)[@shadowhand](https://github.com/shadowhand)

![](https://www.gravatar.com/avatar/e99df56b617f4af8cf0556a51a0ca20c7420104920c57d7e9eab093f92bb744f?d=identicon)[oscarotero](/maintainers/oscarotero)

![](https://www.gravatar.com/avatar/42e0d72f42eb7d84f67e20d28606da42e5a3248ca908b1eadb4366aafeae2561?d=identicon)[filisko](/maintainers/filisko)

---

Top Contributors

[![oscarotero](https://avatars.githubusercontent.com/u/377873?v=4)](https://github.com/oscarotero "oscarotero (67 commits)")[![shadowhand](https://avatars.githubusercontent.com/u/38203?v=4)](https://github.com/shadowhand "shadowhand (9 commits)")[![filisko](https://avatars.githubusercontent.com/u/8798694?v=4)](https://github.com/filisko "filisko (5 commits)")[![brayniverse](https://avatars.githubusercontent.com/u/945367?v=4)](https://github.com/brayniverse "brayniverse (1 commits)")[![sagikazarmark](https://avatars.githubusercontent.com/u/1226384?v=4)](https://github.com/sagikazarmark "sagikazarmark (1 commits)")[![jiripudil](https://avatars.githubusercontent.com/u/1042159?v=4)](https://github.com/jiripudil "jiripudil (1 commits)")[![itsjavi](https://avatars.githubusercontent.com/u/122741?v=4)](https://github.com/itsjavi "itsjavi (1 commits)")[![jakejohns](https://avatars.githubusercontent.com/u/174708?v=4)](https://github.com/jakejohns "jakejohns (1 commits)")

---

Tags

handlerhttpmiddlewarepsr-15requesthttprequestpsr-7middlewareinvokeserverhandlerpsr-15controller

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/middlewares-request-handler/health.svg)

```
[![Health](https://phpackages.com/badges/middlewares-request-handler/health.svg)](https://phpackages.com/packages/middlewares-request-handler)
```

###  Alternatives

[psr/http-server-handler

Common interface for HTTP server-side request handler

177101.3M921](/packages/psr-http-server-handler)[middlewares/fast-route

Middleware to use FastRoute

96191.1k15](/packages/middlewares-fast-route)[middlewares/whoops

Middleware to use Whoops as error handler

33205.4k24](/packages/middlewares-whoops)[middlewares/error-handler

Middleware to handle http errors

14104.2k13](/packages/middlewares-error-handler)[middlewares/negotiation

Middleware to implement content negotiation

47442.1k11](/packages/middlewares-negotiation)[middlewares/payload

Middleware to parse the body of the request with support for json, csv and url-encode

32466.8k17](/packages/middlewares-payload)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)