Download the PHP package beebmx/kirby-middleware without Composer

Kirby Middleware

Kirby Middleware provides a powerful mechanism for inspecting and filtering requests entering your Kirby site.

Overview

• 1. Installation
• 2. Usage
• 3. Middleware
• 4. Options
• 5. Facades
• 6. Plugins
• 7. Roadmap
• 8. License
• 9. Credits

Installation

Download

Download and copy this repository to /site/plugins/kirby-middleware.

Composer

Usage

Out of the box, you don't need to do anything to start using (except for installation). When you install the Kirby Middleware package, it comes with two ways of management middlewares, global middlewares and groups of middlewares.

Global middlewares

This middleware will always be triggered in every Page by the Middleware handler. Out of the box comes with a TrimStrings middleware, which will remove spaces in the Request made.

[!NOTE] To access to this request, you should call the Beebmx\KirbyMiddleware\Request instance.

The Kirby\Http\Request instance will never be modified.

You can access to the Request instance transformed with:

You can add features to the global middleware in your config.php file:

[!NOTE] You can add as much middleware as requested.

They can be a class or a Closure.

TrimStrings

TrimStrings clean all the inputs in the request, but sometimes you need to ignore some inputs to be trimmed; you can skip it with:

And you can recover those inputs with the Request instance in your controllers, models or any place required with:

Or for your convinience you can use the facade:

Group middlewares

The group middlewares will depend on routes to be triggered. By default, the group middleware comes with the web, auth and guest middleware, it brings a ValidateCsrfToken middlewares.

You can set the routes by adding the routes values in your config.php file:

[!NOTE] You can add a pattern like any Kirby route

By default, the web group comes with the (:all) route.

The auth and guest middlewares are inactive by default, but you can customize the routes to enable them.

And of course, you can add more features to the web middleware in your config.php file:

If the web group is not what you need, you can add a new group of middleware. You can add it within the config.php file:

The Middleware Group should looks like:

[!IMPORTANT] All the group middleware classes should extend Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup class.

ValidateCsrfToken

When you use an HTML form with POST, PUT, PATCH, or DELETE in your template, you should include a hidden CSRF _token field in the form so that the CSRF protection middleware can validate the request.

[!NOTE] For convenience, you can also use csrf, csrf-token or _token.

Sometimes you need to ignore some routes from the CSRF validation; you can skip it with:

Security middlewares

Kirby Middleware comes with two (auth and guest) middlewares to improve your security flow based on user authentication.

Auth middleware

The auth middleware provides a starting point to validate if the user is authenticated and if the user is able to visit given routes. If not, it will redirect to some URL to perform a proper login.

Heres an example of it:

[!NOTE] If the user is not authenticated, the middleware will redirect to a guest page.

Guest middleware

The guest middleware provides a starting point to validate if the visitor is a guest and is unauthenticated. If the user is authenticated, it will redirect to some URL to be inside a secured welcome page or dashboard.

Heres an example of it:

[!NOTE] If the user is authenticated, the middleware will redirect to a auth page.

Middleware

When you create a middleware, you can use a class or a Closure; it will depend on your needs and complexity.

Middleware class

When you create your own middleware class, it should look like:

As you can see, handle requires two parameters: a Request called $request and a Closure called $next. The $request contains the current request made in Kirby by the hook route:before.

The second parameter $next, you should call it at the end of the process to proceed to the next middleware validation with the $request.

If you need, some validations can prevent to continue with any other validation; you can throw an error or make a response redirection:

Or with an exception:

Closure middleware

The easiest way to add a global, web, auth or guest middleware is with a Closure; when you add a closure, it should look like:

[!IMPORTANT] Remember to call the $next closure to proceed to the next validation with the $request.

Options

Disable middleware

You can completly disable all middleware validations updating the enable value in the config.php file:

Facades

There are some facades to simplify the use of this plugin:

Plugins

If you are creating your own plugin, and it's required to use some type of request manipulation, Kirby Middleware is also for you.

Installation

First, you need to inform Kirby Middleware than you have some global middleware or group middleware to register.

The easyest way to do this, is with a hook

Global methods

You can add your own validations to the global middleware. To achieve this, you have several methods.

Append

The append method adds the middleware to the end of the global middleware.

Prepend

The prepend method adds the middleware to the beginning of the global middleware.

getGlobalMiddleware

The getGlobalMiddleware method returns an array of all the global middleware registered.

Group methods

You can add your own validations to the groups middleware. To achieve this, you have several methods.

Append

The appendToGroup method adds the middleware to the end of the groups middlewares.

prependToGroup

The prependToGroup method adds the middleware to the beginning of the groups middlewares.

removeFromGroup

The removeFromGroup method removes some middleware from a specific group middleware.

addClassToGroup

The addClassToGroup method adds a Middleware Group class to the groups middlewares.

getMiddlewareGroups

The getMiddlewareGroups method returns an array of all the groups middleware registered.

Authenticate middleware

You can customize the Authenticate middleware without using options, but hook system.loadPlugins:after.

redirectUsing

To set the route to redirect if the user is not authenticated.

setRoutes

If you want to set the routes for the AuthMiddlewareGroup.

RedirectIfAuthenticated middleware

You can customize the RedirectIfAuthenticated middleware without using options, but hook system.loadPlugins:after.

redirectUsing

To set the route to redirect if the user is authenticated.

setRoutes

If you want to set the routes for the GuestMiddlewareGroup.

[!IMPORTANT] Remember, all the group middleware classes should extend Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup class.

Roadmap

• [ ] Custom hooks
• [ ] More global middlewares by default
• [ ] More web middlewares by default
• [x] An auth middleware group.
• [x] A guest middleware group.

License

Licensed under the MIT.

Credits

• Fernando Gutierrez @beebmx
• All Contributors