Skip to content

Latest commit

 

History

History
48 lines (38 loc) · 3.47 KB

psr-15_implementation.md

File metadata and controls

48 lines (38 loc) · 3.47 KB
Raw

How Core implements PSR-15 (HTTP Server Request Handlers)

Although PSR-15 is best known for being "PSR for middlewares", this PHP-FIG recommendation has a wider scope, defining both MiddlewareInterface and RequestHandlerInterface, working in combination.

Core only implements RequestHandlerInterface on his own (Core\RequestHandler class), letting PSR-15 middleware creators implement MiddlewareInterface by themselves.

Understanding middlewares (in Ancient Egypt)

In PHP, middlewares are pieces of software that can modify or intercept an incoming request before it being processed by a controller, and modify or intercept outcoming responses (either generated by a controller or a middleware) before it being sent to client.

Think of your application as an egyptian temple (back to when it was complete and colorful, not in ruins...), with multiple halls in it, each hall leading to another. You are the HTTP request, entering the first hall, and everything goes well. You passed the first middleware. In the second hall, you are given a tool, to be use in the third hall they said. The third hall is a dead-end, with a beautiful golden statuette. You are in controller. You take the statuette, and go back to where you're from. You "changed" from HTTP request to HTTP response. You will pass through the halls you already visited, in reverse order, and if everyone finds it normal you now have a magnificent statuette in your hands (lucky you), you will make your way to temple exit. Maybe in second hall, someone will log that you left with a statuette.

This is how middlewares works, and how Core works.

The role of Core RequestHandler

Core RequestHandler class, implementing PSR-15 RequestHandlerInterface, is responsible for :

  • managing middleware stack (declared in configuration) ;
  • instantiating controller ;
  • calling appropriate controller method (defined in routing table).

Internally, what Core RequestHandler does is passing itself as second parameter to MiddlewareInterface::process() method until middleware stack is exhausted ; then it instantiates your controller and calls the method you define.

Middlewares are called in the order you declared them in configuration (the first middleware declared will be the first to receive ServerRequestInterface instance), so they receive any ResponseInterface in reverse order (the first middleware declared will be the last to receive ResponseInterface instance).

Am I required to have middlewares in my application?

Absolutely not. You can omit all the middleware-specific part of Core configuration and everything will be fine. But middlewares are a way to move common request and response processing away from the application layer (quoting PSR recommendation here), and thus very useful.

Without middlewares, your controllers are required to implement some beforeFilter and/or afterFilter methods (looking at you, CakePHP) to house all of common logic between your controllers, especially when this logic can return a ResponseInterface before any specific controller method being called.

Using PSR-15 middlewares also allows you to require whatever PSR-15 compliant middleware-providing package(s) you want through Composer, and not worry about interoperability. Sounds great, huh?