Download the PHP package nimbly/limber without Composer

Limber

A super minimal PSR-7, 15, and 11 compliant HTTP framework that doesn't get in your way.

Limber is intended for advanced users who are comfortable setting up their own framework and pulling in packages best suited for their particular use case.

Limber includes

• A router
• PSR-7 HTTP message compliant
• PSR-11 container compliant
• PSR-15 middleware compliant
• A thin Application layer to tie everything together

Requirements

• PHP 8.2+
• PSR-7 HTTP Message library

Installation

Quick start

Install PSR-7 library

Limber does not ship with a PSR-7 implementation which is required to receive HTTP requests and send back responses. Let's pull one into our project.

• slim/psr7
• laminas/laminas-diactoros
• guzzlehttp/psr7
• nimbly/Capsule

Sample application

1. Create your entrypoint (or front controller), for example index.php, and start by creating a new Router instance and attaching your routes to it.

2. Once your routes have been defined, you can create the Application instance and pass the router in to it.

3. You can then dispatch requests through the application and receive a response back.

4. And finally, you can send a response back to the calling client.

Advanced configuration

A note on autowiring support

Limber will invoke your route handlers using reflection based autowiring. The ServerRequestInterface instance, URI path parameters defined in the route, and request attributes will be automatically resolved for you, without the need of a PSR-11 container.

However, any domain specific services and classes that are required in your handlers, should be defined in a PSR-11 container instance.

Adding PSR-11 container support

Limber is able to autowire your request handlers and middleware with the aid of a PSR-11 container instance. However, Limber does not ship with a PSR-11 Container implementation, so you will need to bring your own if you require one. Here are some options:

• PHP-DI
• nimbly/Carton

Let's add container support to our application.

And update our entry point by passing the container instance into the Application constructor.

Middleware

Limber supports PSR-15 middleware. All middleware must implement Psr\Http\Server\MiddlewareInterface.

You can pass middleware as one or more of the following types:

• An instance of MiddlewareInterface
• A class-string that implements MiddlewareInterface
• A class-string that implements MiddlewareInterface as an index and an array of key=>value pairs as parameters to be used in dependency injection when autowiring.

Any class-string types will be autowired using the Container instance (if any) for dependency injection.

If auto wiring fails, a DependencyResolutionException exception will be thrown.

Now let's add this global middleware layer to the Limber application instance.

HTTP Exceptions

Limber has most major HTTP error response codes (4xx and 5xx response codes) mapped to exceptions that extend the Nimbly\Limber\Exceptions\HttpException abstract. For example Nimbly\Limber\Exceptions\NotFoundHttpException (404 Not Found). These exceptions have methods to get the HTTP response status code and as well as any response headers that may be required for that response code.

Coupled with a default exception handler (see next section), you can create a single source for crafting HTTP error responses.

Exception handling

You can set a custom default exception handler that will process any exception thrown within the middleware chain.

The exception handler must implement Nimbly\Limber\ExceptionHandlerInterface.

NOTE Exceptions thrown outside of the middleware chain (e.g. during bootstrap process) will continue to bubble up unless caught elsewhere.

Now let's add the exception handler to the Limber application instance.

Router

The Router builds and collects Route instances and provides helper methods to group Routes together sharing a common configuration (path prefix, namespace, middleware, etc).

Defining routes

Create a Router instance and begin defining your routes. There are convenience methods for all major HTTP verbs (get, post, put, patch, and delete).

A route can respond to any number of HTTP methods by using the add method and passing an array of methods as strings.

HEAD requests

By default, Limber will add a HEAD method to each GET route.

Route paths

Paths can be static or contain named parameters. Named parameters will be injected into your route handler if the handler also contains a parameter of the same name.

In the following handler, both the $request and $isbn parameters will be injected automatically.

Route path patterns

Your named parameters can also enforce a specific regular expression pattern when being matched - just add the pattern after the placeholder name with a colon.

Limber has several predefined path patterns you can use:

• alpha Alphabetic characters only (A-Z and a-z), of any length
• int Integer number of any length
• alphanumeric Any combination of number or alphabetic character
• uuid A Universally Unique Identifier or sometimes known as a GUID.
• hex A hexidecimal value, of any length

You can define your own patterns to match using the Router::setPattern() static method.

Route handlers

Route handlers may either be a callable or a string in the format Fully\Qualified\Namespace\ClassName@Method (for example App\Handlers\v1\BooksHandler@create).

Route handlers must return a ResponseInterface instance.

Limber uses reflection based autowiring to automatically resolve your route handlers including constructor and function/method parameters. The ServerRequestInterface instance, path parameters, and any attributes attached to the ServerRequestInterface instance will be resolved and injected for you. This applies for both closure based handlers as well as Class@Method based handlers.

You may also optionally supply a PSR-11 compliant ContainerInterface instance to aid in route handler parameter resolution. By doing this, you can easily have your application specific dependencies resolved and injected into your handlers by Limber. See PSR-11 Container support section for more information.

Route configuration

You can configure individual routes to respond to a specific scheme, a specific hostname, process additional middleware, or pass along attributes to the ServerRequestInterface instance.

Scheme

Route specific middleware

Hostname

Attributes

Route groups

You can group routes together using the group method and all routes contained will inherit the configuration you have defined.

• scheme (optional) string The HTTP scheme (http or https) to match against. A null value will match against any value.
• middleware (optional) array<string> or array<MiddlewareInterface> or array<callable> An array of all middleware classes (fully qualified namespace) or actual instances of middleware.
• prefix (optional) string A string prepended to all URIs when matching the request.
• namespace (optional) string A string prepended to all string based handlers before instantiating a new class.
• hostnames (optional) array<string> An array of hostnames to be matched against.
• attributes (optional) array<string,mixed> An array of key=>value pairs representing attributes that will be attached to the ServerRequestInterface instance if the route matches.
• routes (required) callable A callable that accepts the Router instance where you can add additional routes within the group.

Groups can be nested and will inherit their parent group's settings unless the setting is overridden. Middleware settings however are merged with their parent's settings.

Using with React/Http

Because Limber is PSR-7 compliant, it works very well with react/http to create a standalone HTTP service without the need for an additional HTTP server (nginx, Apache, etc) - great for containerizing your service with minimal dependencies.

Install React/Http

Create entry point

Create a file called main.php (or whatever you want) to be the container's command/entry point.

Adding process signal handlers

React/Http supports tapping into processing signals, commonly used by container orchestration systems to shutdown processes. You can use these interrupts to signal to React/Http to stop the event loop. This functionality requires the PHP pcntl module be installed. (See next section.)

Create Dockerfile

Create a Dockerfile in the root of your application.

We'll extend from the official PHP 8.2 docker image and add some useful tools like composer, a better event loop library from PECL, and install support for process control (pcntl). Process control will allow your service to shutdown gracefully when a SIGINT or SIGHUP signal is received.

Obviously, edit this file to match your specific needs.

Build docker image

Run as container