Telegraph is essentially a "request-only" (as vs "request + response") variation of Relay.
For middleware to use with Telegraph, please review telegraph/middleware.
A Telegraph middleware callable must have the following signature:
A Telegraph middleware callable must return an implementation of Psr\Http\Message\ResponseInterface.
This signature makes Telegraph appropriate for both server-related and client- related use cases. That is, it can receive an incoming ServerRequestInterface and generate an outgoing ResponseInterface (acting as a server), or it can build an outgoing RequestInterface and return the resulting ResponseInterface (acting as a client).
N.b.: Psr\Http\Message\ServerRequestInterface extends RequestInterface, so typehinting to RequestInterface covers both use cases.
$queue array of middleware callables:
Use the TelegraphFactory to create a Telegraph object with the
and dispatch a request through the Telegraph object to get back a response.
That will execute each of the middlewares in first-in-first-out order.
Your middleware logic should follow this pattern:
Receive the request object from the previous middleware as a parameter, along with a dispatcher to the
Optionally modify the received request;
Then either …
- Create a response and return it to the previous middleware.
Dispatch the request through the
$nextmiddleware, receiving a response in return;
Optionally modify the returned response;
Return the response to the previous middleware.
Here is a skeleton example; your own middleware may or may not perform the various optional processes:
N.b.: You MUST return the response from your middleware logic, whether by creating it or by using the one returned from the
As a reminder, remember that the request is immutable. Implicit in that is
the fact that changes to the request are always transmitted to the
middleware but never to the previous one.
Note also that this logic chain means the request is modified on the way “in” through the middleware, and the response is modified on the way “out”.
For example, if the middleware queue looks like this:
… the path through the middlewares will look like this:
Foo is 1st on the way in Bar is 2nd on the way in Baz is 3rd on the way in, and 1st on the way out Bar is 2nd on the way out Foo is 3rd on the way out
You can use this dual-pass logic in clever and perhaps unintuitive ways. For
example, middleware placed at the very start may do nothing with the request
$next right away, but it is the middleware with the “real” last
opportunity to modify the response.
At some point, one of your middleware callables will need to create a response to return to the previous middleware. Because there are different response implementations, Telegraph will not create one for you; the choice of response implementation is up to you.
Here is an example of a response-creating middleware:
In general, there should be no need to call
$next at this point; merely
return the response to start its journey back through the middleware queue. As
such, the response-creating middleware entry is probably going to the the very
last one in the queue.
You may wish to use
$queue entries other than anonymous functions or already-
instantiated objects. If so, you can pass a
$resolver callable to the
Telegraph that will convert the
$queue entry to a callable. Thus, using a
$resolver allows you to pass in your own factory mechanism for
For example, this
$resolver will naively convert
$queue string entries to
new class instances:
You can then add
$queue entries as class names, and Telegraph will use the
$resolver to create the objects in turn.
As long as the classes listed in the
__invoke(RequestInterface $request, callable $next), then Telegraph will work
Sometimes using an array for the
$queue will not be suitable. You may wish to
use an object to build the middleware queue instead.
In these cases, you can use the TelegraphFactory to create the Telegraph
queue from any object that eimplements Traversable. The TelegraphFactory
will then convert that queue object to an array using
You can then dispatch through the
$telegraph as described above.
If you wish, you can reuse the same Telegraph object multiple times. The same middleware queue will be used each time you invoke that Telegraph instance. For example, if you are making multiple client requests:
If you are certain that you will never reuse the Telegraph instance, you can instantiate a single-use Dispatcher to avoid some minor overhead.