beebmx / kirby-patrol
Kirby Patrol for Kirby 4
Installs: 36
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 2
Forks: 0
Open Issues: 0
Type:kirby-plugin
Requires
- php: ^8.2
- beebmx/kirby-middleware: ^1.0
- getkirby/composer-installer: ^1.1
Requires (Dev)
- getkirby/cms: ^4.2
- laravel/pint: ^1.10
- pestphp/pest: ^2.0
- spatie/ray: ^1.40
README
Kirby Patrol
An easy and customizable way to manage access to website pages according to the roles assigned to users within the Kirby panel interface.
Overview
Installation
Download
Download and copy this repository to /site/plugins/kirby-patrol
.
Composer
composer require beebmx/kirby-patrol
Usage
Out of the box, you don't need to do anything to start using (except for installation),
but if you require customizing the default behavior, there are some options to personalize Kirby Patrol
.
Panel
All users with panel access will see the new area and will be able to update the access to the pages on the website.
If you need to restrict this behavior, you can do so by adding the permission in the user YAML file:
title: Editor permissions: beebmx.kirby-patrol: access: false
Note
The access
is set to true
by default
The pages displayed in the new panel area will be all the site
childrens published (with status listed
and unlisted
)
and two levels inside every page. If you need a specific collection of pages you can change it with the query
option
in your config.php
file:
use Kirby\Cms\App; use Kirby\Cms\Pages; use Kirby\Cms\Site; 'beebmx.kirby-patrol' => [ 'content' => [ 'query' => function (Site $site, Pages $pages, App $kirby) { return $site->find('secure-page')->children()->listed(); }, ], ],
And if you need to update the depth
of the pages displayed, update the config.php
file:
'beebmx.kirby-patrol' => [ 'content' => [ 'depth' => 3, ], ],
Here's an example of Kirby Patrol
view page:
Frontend
When a logged-in user visits any page, Kirby Patrol
will automatically validate the request. If the user has access
to the visited page, they can normally view the content, but if not, an error page will be thrown with a 401
status code.
Warning
It's important that you use a logged-in user when the validation occurs; otherwise, an error will be thrown. If the default
Middleware
Even when Kirby Patrol
tries to validate a user, it's possible that behavior won't be enough for your own validation.
In that case, you can customize and add additional restrictions to every page.
The middleware process is powered by Kirby Middleware, and you can use all features if you need to.
Closure middleware
The easyest way to add additional validation is with Closures
.
Added this in the config.php
file:
use Kirby\Http\Response; use Beebmx\KirbyMiddleware\Request; 'beebmx.kirby-patrol' => [ 'permissions' => [ 'middleware' => [ function (Request $request, Closure $next) { if(page($request->path())->is('secure-page')) { return Response::redirect('login') } return $next($request); }, ], ], ],
As you can see, the Closure
requires two parameters: an Request
called $request
and a Closure
called $next
.
The $request
contains the stack of previous validations from Patrol and any other middleware triggered.
The second parameter $next
, you should call it at the end of the process to proceed to the next validation with the $request
.
Note
You can return a Response::class
object. When you do that, Kirby Patrol
will automatically send the request.
Class middleware
If your own validation is more complex for a simple Closure
, you can use a custom class for that purpose:
'beebmx.kirby-patrol' => [ 'permissions' => [ 'middleware' => [ MyCustomMiddleware::class, ], ], ],
And your class should look like:
use Beebmx\KirbyMiddleware\Request; use Closure; use Kirby\Cms\App; use Kirby\Exception\ErrorPageException; class MyCustomMiddleware { public function handle(Request $request, Closure $next) { $kirby = App::instance(); if ($kirby->site()->isDisabled()->toBool()) { return throw new ErrorPageException([ 'fallback' => 'Unauthorized', 'httpCode' => 401, ]); } return $next($data); } }
Your middleware logic should be inside the handle
method; otherwise, the middleware will never be triggered.
Note
You can throw an exception ErrorPageException::class
with your custom data in case you need it.
Redirection
Sometimes you don't need an error in your website to display an error, in that cases you can make a redireccion:
'beebmx.kirby-patrol' => [ 'permissions' => [ 'redirect' => 'login', ], ],
As you can see, when a redirection is set, you don't need to customize an extra middleware
.
Utilities
You have utilities available to incorporate into your existing workflow:
User utilities
If you want to validate if a user
has access to a given Page:
user()->can($page)
Note
Page can be a string
or a Kirby\Cms\Page
object
If you want to retrieve all the pages with access or without access
user()->patrol(bool)
Note
A true
value returns all pages with access.
A false
value returns all pages without access.
Pages utility
If you want to know if a pages
collection have access or not:
pages()->patrol(bool)
Note
A true
value returns all pages with access.
A false
value returns all pages without access.
Options
Here's an example of a full use of the options from the config.php
file:
use Beebmx\KirbyMiddleware\Request; use Closure; 'beebmx.kirby-patrol' => [ 'name' => 'Profiles', 'icon' => 'shield', 'content' => [ 'columns' => 4, 'depth' => 3, 'query' => function (Site $site, Pages $pages, Kirby $kirby) { return $site->find('private-content')->children()->listed(); }, ], 'permissions' => [ 'redirect' => 'login', 'default' => true, 'middleware' => [ function (Request $request, Closure $next) { if(page($request->path())->id() === 'super-secret-page') { return throw new ErrorPageException([ 'fallback' => 'Unauthorized', 'httpCode' => 401, ]); } return $next($request); }, ] ], ],
Roadmap
- Custom hooks
- Multilanguage support
- Guest support
License
Licensed under the MIT.
Credits
- Fernando Gutierrez @beebmx
- jonatanjonas
logo
- All Contributors