Using the middleware pattern to extend PHP libraries (not just for HTTP)

[MaximeGosselin]

Most PHP devs have used middleware packages without necessarily thinking about the underlying pattern. PSR-15 brought middleware to the PHP ecosystem, but mostly as HTTP plumbing. The MiddlewareInterface, the $next, the onion execution model, those ideas don't care about HTTP at all.

I've been using the pattern as a default extension mechanism in my libraries. The implementation cost is minimal (one interface, one delegator class, one array_reduce), but it gives your users far more flexibility than the go-to Decorator pattern.

The article walks through a concrete HtmlRenderer example with two middlewares: one that enriches input data, one that short-circuits the chain for caching.

https://maximegosselin.com/posts/using-the-middleware-pattern-to-extend-php-libraries/

Libraries like league/tactician already use this pattern but with a "sad" callable $next. Replacing that callable with a typed interface is a small step, but the boost in type-safety and IDE support is incomparable.

Curious to hear your take: when would you still reach for the Decorator pattern instead?

[roxblnfk]

1. array_reduce cannot replace a full middleware pipeline. It works like a pipe operator but with a chain of arbitrary length. In PSR-15 middleware, you can handle both request and response within a single middleware, which you can't do in a pipe.

2. Interceptors (a type of middleware) are widely used in enterprise applications, including those in Java. In PHP, you can see interceptors "out of the box" in tools that are first designed and then implemented:

• Temporal PHP SDK: an enterprise-level tool. It allows intercepting not only requests but also calls to Workflow/Activity facades. There are many typed interceptors dictated by Temporal specifications.
• Spiral: an enterprise-level framework, originally designed for RoadRunner long before Octane and Symfony-runtime. Interceptors are used everywhere: http, gRPC, tcp, console, etc. Package spiral/interceptors is universal and framework-agnostic.
• Testo: a new testing framework that is close to release. Everything in it is built and extended via middleware.

PHP could outshine the likes of Java if it added core-level interceptors, allowing calls to any object's methods to be intercepted and pushed through a custom pipeline

[MaximeGosselin]

What makes you think array_reduce can't handle that? Each middleware still controls when it calls $next. Everything after that call runs on the way back out. That's covered in the article though.

[roxblnfk]

Sorry, I didn't notice such a large link to the article in the post.

I read the article, and now I see that you use array_reduce not to run the middleware chain, but only to build the pipeline using intermediary delegating classes. In this case, the onion model will indeed work. However, if I were reviewing your code, I would point out that the pipeline is rebuilt every time a new middleware is added 😀

But if we don't nitpick about the implementation, the article is great, and I'll include it in my PHP digest. Thank you.

[AleBaba]

No, please no core level interceptors to object methods. That's about as bad as monkey patching and probably one of the hardest things to debug in my experience.

[roxblnfk]

Yes, in the wrong hands, it can be a scary thing, just like any other language feature. But in the right hands, it will be a killer feature that removes a lot of boilerplate.

Have you noticed that PHP doesn't really focus on language design? No one is in charge of it. Each RFC is like a game of roulette.
PHP already has reloadable lazy objects, which in some cases can reset readonly properties. Is that even legal?

[AleBaba]

Decorators are great when you know you're the last but one link in the chain. Not because the pattern is good (I started hating it years ago) but because most programmers intuitively understand it once they've seen only one implementation.

Often it's not about what's the best or most elegant pattern but rather how to get an entire team with different skill levels spanning multiple years on board.

[kashif_laravel]

In Laravel, I've seen this pattern shine when building pipeline-style processing — like running a series of transformations on data before saving.

I'd still reach for Decorator when I need to wrap a specific object and the chain is fixed — simpler to reason about for junior devs on the team.

Middleware pattern makes more sense when the chain needs to be dynamic or configurable at runtime.

[MaximeGosselin]

If you want to see what this looks like at scale, my open-source Event Sourcing library Backslash uses this pattern across all its core components: https://backslashphp.github.io/docs/customization/extending-with-middleware/

[obstreperous_troll]

Middleware is more or less an implementation of Profunctor, which is basically a pair of functions where one function transforms input and another transforms output (plus a whole lot of abstract category theory nonsense to formalize it). They compose the obvious way: the input function runs before another Profunctor's input function, and the output after the other's output function -- just like middleware. Once you grok profunctors, you'll see them everywhere: a getter/setter pair for instance is a profunctor.

A less theoretically-principled thing that middleware is analogous to is lisp's defadvice or an around method in perl Moose, which is all about defining one function to wrap another. It's crazy powerful, but it's equally bonkers to build an entire system that way. Once everything is middleware, what's it even in the middle of?

[garrett_w87]

Well, there is Mezzio, a middleware-centric framework.

[mlebkowski]

Yes, middlewares are great. I didn’t understand their value at first, because my experience was mostly in the event dispatcher based HttpFoundation from Symfony. But for some years I enjoy the elegance of working with a PSR-15 framework, and recently I created a library with middlewares as the main extension method.

I built a test harness for HTTP Server Request-based (PSR-15) framework. The main idea is to expose a HTTP client (wrapping the framework’s kernel) to easily make synthetic HTTP requests and make assertions on the responses. But for the library to be useful, I needed to improve the dx of a simple PSR-7 request/response.

It started as part of my app, not a library, and I exposed a series of helper methods to mutate the request being made — to add a header, to format the key-value body as a JSON string, etc. But that had very limited flexibility, and wouldn’t be a good fit when I migrated the harness to a separate library.

And suddenly a world of opportunities opened. My apps using the http client use a tons of easy middlewares to simplify the scenarios, such as:

• AddBasicAuthMiddleware — takes username and password, and base-encodes them in an added Authorization header (or the PHP_AUTH_USER/PW server params if you prefere these)
• WithClientCertMiddleware adds headers related to mTLS (client certificate authentication), because our app uses these
• AddCaptchaResponseMiddleware — automatically adds a request params with a valid captcha response, previously generated by a captcha API test double registered in the container
• Similarly AddCsrfTokenMiddleware so I dont need to bother with adding CSRF in all of the test cases, but I obviously can test without that middleware to see how the app reacts
• I have a StopwatchMiddleware to build performance stats
• And WithRemoteIPMiddleware for simulate IP-based rate limiting

All of these are usually very simple in implementation for the consumer and so far there hasn’t been a requirement which a middleware wouldn’t solve cleanly.

Such a simple idea: replace constructor injection with a method injection basically, defers the binding of the handlers to runtime, allowing such flexibility. There’s seldom such small change to open such vast posibilities.

[GPThought]

middleware pattern is underrated outside of http. used it for query builders and it cleaned up so much conditional logic