Download the PHP package inroutephp/inroute without Composer

Generate http routing and dispatching middleware from docblock annotations.

Inroute is a code generator. It scans your source tree for annotated routes and generates a PSR-15 compliant http routing middleware. In addition all routes have a middleware pipeline of their own, making it easy to add behaviour at compile time based on custom annotations.

• See the example-app for a complete example.
• See console for a compiler tool for the command line.

Installation

Table of contents

1. Writing routes
2. Piping a route through a middleware
3. Compiling
4. Dispatching
5. Generating route paths
6. Creating custom annotations
7. Processing routes using compiler passes
8. Handling dependencies with a DI container
9. Dealing with routing errors

Writing routes

Routes are annotated using annotations, are called with a PSR-7 request object and inroute environment and are expected to return a PSR-7 response.

• The method and path values are self explanatory.
• A route name is optional, and defaults to class:method (in the example UserController:getUser).
• Attributes are custom values that can be accessed at runtime through the request object.
• Note that the use of Laminas diactoros as a psr-7 response implementation is used in this example, you may of course use another psr-7 implementation.

Piping a route through a middleware

Each route has a PSR-15 middleware pipeline of its own. Adding a middleware to a route can be done using the @Pipe annotation. In the following example the pipedAction route is piped through the AppendingMiddleware and the text ::Middleware is appended to the route response.

Compiling

The recommended way of building a project is by using the console build tool. Compiling from pure php involves setting up the compiler something like the following.

Possible settings include

• container: The classname of a compile time container, specify if needed.
• bootstrap: Classname of compile bootstrap, default should normally be fine.
• source-dir: Directory to scan for annotated routes.
• source-prefix: psr-4 namespace prefix to use when scanning directory.
• source-classes: Array of source classnames, use instead of or togheter with directory scanning.
• ignore-annotations: Array of annotations to ignore during compilation
• route-factory: Classname of route factory, default should normally be fine.
• compiler: Classname of compiler to use, default should normally be fine.
• core-compiler-passes: Array of core compiler passes, default should normally be fine.
• compiler-passes: Array of custom compiler passes.
• code-generator: The code generator to use, default should normally be fine.
• target-namespace: The namespace of the generated router (defaults to no namespace).
• target-classname: The classname of the generated router (defaults to HttpRouter).

OpenApi

Please note that reading openapi annotations is still very rudimentary. Please open an issue if you have suggestions on more values that should be parsed.

Instead of using the built in annotations inroute is also able to build openapi projects annotated with swagger-php annotations.

Set the core-compiler-passes setting to ['inroutephp\inroute\OpenApi\OpenApiCompilerPass'].

Dispatching

The generated router is a PSR-15 compliant middleware. To dispatch you need to supply an implementation of PSR-7 for request and response objects and some response emitting functionality (of course you should also use a complete middleware pipeline for maximum power).

In this simple example we use

• laminas-diactoros as PSR-15 implementation.
• laminas-httphandlerrunner for emitting responses.
• The built in middleware pipeline for dispatching.

Or to send to piped example from above

Generating route paths

Creating custom annotations

Inroute uses doctrine to read annotations. Creating custom annotations is as easy as

To create annotations that automatically pipes a route through a middleware use something like the following.

Note that you need to supply the AuthMiddleware to authenticate a user and the RequireUserGroupMiddleware to check user priviliges for this example to function as expected. See below on how to inject a dependency container that can deliver these middlewares.

And to annotate your controller methods

Processing routes using compiler passes

Custom annotations are most useful pared with custom compiler passes.

Each route has a middleware pipeline of its own. In the example above all routes annotated with MyAnnotation will be wrapped in SomeCoolMiddleware. This makes it easy to add custom behaviour to routes at compile time based on annotations.

The attribute cool-attribute can be accessed in middlewares using $request->getAttribute('cool-attribute').

Handling dependencies with a DI container

You may have noted that in the example above SomeCoolMiddleware was passed not as an instantiated object but as a class name. The actual object is created at runtime using a PSR-11 compliant dependency injection container. The same is true for controller classes.

Create you container as part of your dispatching logic and pass it to the router using the setContainer() method.

Dealing with routing errors

Route note found (http code 404) and method not allowed (405) situations can be handled in one of two ways.

Using a ResponseFactoryInterface

If you container contains a service Psr\Http\Message\ResponseFactoryInterface then that factory will be used to create and return a 404 or 405 http response.

Catching exceptions

If no factory is defined a inroutephp\inroute\Runtime\Exception\RouteNotFoundException or inroutephp\inroute\Runtime\Exception\MethodNotAllowedException will be thrown.