README

Patrol for Kirby

An easy and customizable way to manage access to website pages according to the roles assigned to users within the Kirby panel interface.

Overview

• 1. Installation
• 2. Usage
• 3. Options
• 4. Roadmap
• 5. License
• 6. Credits

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 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.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.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.patrol' => [
    'content' => [
        'depth' => 3,
    ],
],

Here's an example of Patrol view page:

Frontend

When a logged-in user visits any page, 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 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 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.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, 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.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.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

Warning

Since version 1.3.0, Patrol changes the plugin prefix from beebmx.kirby-patrol to beebmx.patrol.

Here's an example of a full use of the options from the config.php file:

use Beebmx\KirbyMiddleware\Request;
use Closure;

'beebmx.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