Kirby Middleware
provides a powerful mechanism for inspecting and filtering requests entering your Kirby
site.
- 1. Installation
- 2. Usage
- 3. Middleware
- 4. Options
- 5. Facades
- 6. Plugins
- 7. Roadmap
- 8. License
- 9. Credits
Download and copy this repository to /site/plugins/kirby-middleware
.
composer require beebmx/kirby-middleware
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.
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:
use Beebmx\KirbyMiddleware\Request;
$request = Request::instance();
You can add features to the global
middleware in your config.php
file:
'beebmx.kirby-middleware' => [
'global' => [
MyOwnGlobalMiddleware::class,
],
],
Note
You can add as much middleware as requested.
They can be a class
or a Closure
.
TrimStrings
clean all the inputs in the request, but sometimes you need to ignore some inputs
to be trimmed; you can skip it with:
'beebmx.kirby-middleware' => [
'exceptions' => [
'trim' => [
'password',
'password_confirmation',
],
],
],
And you can recover those inputs
with the Request
instance in your controllers, models or any place required with:
use Beebmx\KirbyMiddleware\Request;
Request::instance()->get('yourInput')
Or for your convinience you can use the facade:
use Beebmx\KirbyMiddleware\Facades\Request;
Request::get('yourInput')
The group middlewares will depend on routes to be triggered. By default, the group middleware comes with the web
middleware, it brings a ValidateCsrfToken
middleware.
You can set the routes by adding the routes
values in your config.php
file:
'beebmx.kirby-middleware' => [
'routes' => [
'web' => [
'blog/(:any)',
'content/(:alpha)',
'page/(:num)',
]
],
],
Note
You can add a pattern like any Kirby
route
By default, the web
group comes with the (:all)
route.
And of course, you can add more features to the web
middleware in your config.php
file:
'beebmx.kirby-middleware' => [
'web' => [
MyOwnMiddleware::class,
],
],
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:
'beebmx.kirby-middleware' => [
'groups' => [
MyOwnMiddlewareGroup::class,
],
],
The Middleware Group
should looks like:
use Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup;
class MyOwnMiddlewareGroup extends MiddlewareGroup
{
public string $name = 'review';
public string|array $routes = [
'blog/(:any)',
'content/(:alpha)',
];
public array $group = [
ReviewBlogMiddleware::class,
ReviewContentMiddleware::class,
ReviewByAuthorMiddleware::class,
];
}
Important
All the group middleware classes should extend Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup
class.
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.
<form method="POST" action="myPage">
<input type="hidden" name="_token" value="<?= csrf() ?>" />
</form>
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:
'beebmx.kirby-middleware' => [
'exceptions' => [
'csrf' => [
'payment',
'test',
],
],
],
When you create a middleware, you can use a class
or a Closure
; it will depend on your needs and complexity.
When you create your own middleware class, it should look like:
use Beebmx\KirbyMiddleware\Request;
use Closure;
class ValidateSomeInformation
{
public function handle(Request $request, Closure $next)
{
// Perform action
return $next($request);
}
}
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:
use Beebmx\KirbyMiddleware\Request;
use Closure;
use Kirby\Http\Response;
class UserShouldBeAuthenticated
{
public function handle(Request $request, Closure $next)
{
if(empty($request->user())) {
return Response::redirect('login')
}
return $next($request);
}
}
Or with an exception:
use Beebmx\KirbyMiddleware\Request;
use Closure;
use Kirby\Exception\ErrorPageException;
class UserShouldBeAuthenticated
{
public function handle(Request $request, Closure $next)
{
if(empty($request->user())) {
return throw new ErrorPageException([
'fallback' => 'Unauthorized',
'httpCode' => 401,
]);
}
return $next($request);
}
}
The easiest way to add a global
or web
middleware is with a Closure
; when you add a closure, it should look like:
use Beebmx\KirbyMiddleware\Request;
use Closure;
'beebmx.kirby-middleware' => [
'web' => [
function (Request $request, Closure $next) {
// Perform action
return $next($request);
},
],
],
Important
Remember to call the $next
closure to proceed to the next validation with the $request
.
Option | Default | Type | Description |
---|---|---|---|
beebmx.kirby-middleware.enabled | true | bool |
Enable/Disable all Kirby Middleware . |
beebmx.kirby-middleware.exceptions | [] | array |
Set exceptions for trim and csrf middlewares. |
beebmx.kirby-middleware.global | [] | array |
Add your own global middlewares. |
beebmx.kirby-middleware.groups | [] | array |
Add your own groups middlewares. |
beebmx.kirby-middleware.routes | [] | array |
Customize your group routes . |
beebmx.kirby-middleware.web | [] | array |
Add your own web middlewares. |
You can completly disable all middleware validations updating the enable
value in the config.php
file:
'beebmx.kirby-middleware' => [
'enabled' => false,
],
There are some facades
to simplify the use of this plugin:
Facade | Class | Instance of |
---|---|---|
Beebmx\KirbyMiddleware\Facades\Middleware | Beebmx\KirbyMiddleware\Middleware | Middleware::instance() |
Beebmx\KirbyMiddleware\Facades\Pipeline | Beebmx\Pipeline\Pipeline | new Pipeline |
Beebmx\KirbyMiddleware\Facades\Request | Beebmx\KirbyMiddleware\Request | Request::instance() |
If you are creating your own plugin, and it's required to use some type of request manipulation, Kirby Middleware
is also for you.
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
use Kirby\Cms\App as Kirby;
use Beebmx\KirbyMiddleware\Facades\Middleware;
Kirby::plugin('beebmx/kirby-security', [
'hooks' => [
'system.loadPlugins:after' => function () {
Middleware::appendToGroup('security', [
ValidateUser::class,
ValidateUserRole::class,
ValidateUserTeam::class,
]);
},
],
]);
You can add your own validations to the global
middleware. To achieve this, you have several methods.
The append
method adds the middleware to the end of the global
middleware.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::append(ValidateVisitor::class),
The prepend
method adds the middleware to the beginning of the global
middleware.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::prepend(ValidateVisitor::class),
The getGlobalMiddleware
method returns an array of all the global
middleware registered.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::getGlobalMiddleware(),
You can add your own validations to the groups
middleware. To achieve this, you have several methods.
The appendToGroup
method adds the middleware to the end of the groups
middlewares.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::appendToGroup('security', [
ValidateUser::class,
ValidateUserRole::class,
ValidateUserTeam::class,
]);
The prependToGroup
method adds the middleware to the beginning of the groups
middlewares.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::prependToGroup('security', [
ValidateUser::class,
ValidateUserRole::class,
ValidateUserTeam::class,
]);
The removeFromGroup
method removes some middleware from a specific group
middleware.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::removeFromGroup('security', ValidateVisitor::class),
The addClassToGroup
method adds a Middleware Group
class to the groups
middlewares.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::addClassToGroup(SecurityMiddlewareGroup::class),
The getMiddlewareGroups
method returns an array of all the groups
middleware registered.
use Beebmx\KirbyMiddleware\Facades\Middleware;
Middleware::getMiddlewareGroups(),
Important
Remember, all the group middleware classes should extend Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup
class.
- Custom hooks
- More
global
middlewares by default - More
web
middlewares by default - An
auth
middleware group.
Licensed under the MIT.
- Fernando Gutierrez @beebmx
- All Contributors