Search by

johannschopplich / kirby-locked-pages

johannschopplich

Password-protect pages for Kirby CMS

Package info

github.com/johannschopplich/kirby-locked-pages

Homepage

Type:kirby-plugin

pkg:composer/johannschopplich/kirby-locked-pages

Fund package maintenance!

kirby.tools

Statistics

Installs: 4 471

Dependents: 0

Suggesters: 0

Stars: 42

Open Issues: 0

3.4.0 2026-11-16 14:29 UTC

README

Kirby Locked Pages logo

Kirby Locked Pages

Kirby Locked Pages is a plugin for Kirby CMS that password-protects a page, its subpages, and their files behind a login form.

Features • Options • Security Scope

When to Use

I want to… Use
Password-protect a page and its children fields/locked-pages blueprint group
Keep a locked page's images and downloads private Nothing – files follow their page's lock
Lock a page on a multilingual site The toggle in the default language
Give visitors a logout link locked-pages.logout hook
Restyle the password form site/templates/locked-pages-login.php
Check lock state from my own code Guard::isLocked(), Guard::find()
Change the login slug or the form's text johannschopplich.locked-pages options

Features

🔒 Password Protection

Toggle protection on any page through a globally registered blueprint field group. Add it to the fields of the page's blueprint:

fields:
  protection: fields/locked-pages

The group adds a lockedPagesEnable toggle and a lockedPagesPassword field. Visitors are redirected to a login form until they enter the correct password, and the grant is then stored in their session. Drafts and the error page are never locked, even when the fields are set.

Both fields are untranslatable: on a multilingual site, set them in the default language, and they apply to every translation.

🌳 Subtree Inheritance

Locking a page locks its whole subtree – you only add the field group at the subtree root. Unlocking the parent grants access to every descendant without protection of its own, and one unlock covers all translations. Changing the password locks the page again for everyone who unlocked it before. Content representations (.json, .xml, .rss, …) are locked alongside the page.

🖼️ Protected Files

The files of a locked page and its subpages, and their thumbs, reach only visitors who unlocked the page and logged-in users who may read the file. $file->url(), resize(), thumb(), and srcset() return URLs under the login slug, such as /locked/files/notes/…/painting.jpg, instead of the public /media/ folder, so templates need no change. Without access, these URLs answer with 404, and Kirby's media URL of a locked file answers with 404 for everyone. Locked files are sent with Cache-Control: no-store, private.

🔍 Lock State in Templates

Guard::isLocked($page) is true while the page or one of its ancestors is protected and the visitor's session has not unlocked the nearest protected one with its current password. Drafts and the error page are never locked. A Panel login does not unlock the page – only the password does. Guard::find($page) returns the page whose protection applies – the page itself or its nearest protected ancestor – or null when none of them is protected.

To list a locked page in the menu only once the visitor has unlocked it:

<?php use JohannSchopplich\LockedPages\Guard; ?>

<?php foreach ($site->children()->listed() as $item): ?>
  <?php if (!Guard::isLocked($item)): ?>
    <a href="<?= $item->url() ?>"><?= $item->title()->esc() ?></a>
  <?php endif ?>
<?php endforeach ?>

To mark every protected page, unlocked or not – with a lock icon, say – check Guard::find($item) !== null.

🚪 Logout Hook

Clear a visitor's grants by triggering the locked-pages.logout hook. Wire it to a route, then show a logout link only while the session holds a grant.

// config.php
return [
    'routes' => [
        [
            'pattern' => 'logout',
            'action' => function () {
                kirby()->trigger('locked-pages.logout');
                go('/');
            }
        ]
    ]
];
<?php use JohannSchopplich\LockedPages\Guard; ?>

<?php if (kirby()->session()->data()->get(Guard::SESSION_KEY)): ?>
  <a href="<?= url('logout') ?>">Logout</a>
<?php endif ?>

🌐 Translated Login Form

The login form speaks English, German, French, and Dutch, and follows the current language of a multilingual site. A regional code like de-at gets the strings of its base language de. Other languages fall back to the default language, then to English. A single-language site always gets English, whatever its locale option – set the text options to translate the form. The title, label, and error options replace the translated strings in every language.

To add a language, register its five strings through the translations extension of a site plugin:

// site/plugins/locked-pages-translations/index.php
use Kirby\Cms\App;

App::plugin('my/locked-pages-translations', [
    'translations' => [
        'es' => [
            'johannschopplich.locked-pages.title' => 'Página protegida',
            'johannschopplich.locked-pages.password' => 'Contraseña',
            'johannschopplich.locked-pages.submit' => 'Abrir página',
            'johannschopplich.locked-pages.error.password' => 'La contraseña es incorrecta',
            'johannschopplich.locked-pages.error.csrf' => 'El token CSRF no es válido'
        ]
    ]
]);

🎨 Custom Login Template

The plugin ships a self-contained login template. Drop your own locked-pages-login.php into site/templates/ and Kirby uses it automatically – the bundled template is a good starting point. It receives:

  • $error: the message after a failed attempt, otherwise false.
  • $passwordLabel: the label of the password field, from the label.password option or the translation.
  • $submitLabel: the label of the submit button, from the label.submit option or the translation.
  • $page: the login page, not the locked one – its title() is the form's title.

They arrive unescaped – escape them as the bundled template does. A template copied from an earlier release does not print $passwordLabel and $submitLabel, so the label options and the strings of a base language apply only once it does.

The form must send a POST request to the URL it was served from, with a password field and a csrf field holding csrf() – leave action off the form, as the bundled template does.

Requirements

  • Kirby 5 or 6

Installation

Composer (Recommended)

composer require johannschopplich/kirby-locked-pages

Manual Installation

Download a release and extract it to /site/plugins/kirby-locked-pages.

Options

All options are namespaced under johannschopplich.locked-pages:

Option Default Description
slug locked Slug of the login form and prefix of protected file URLs. On a multilingual site, the form sits under the language prefix, e.g. /de/locked.
template locked-pages-login Template name for the login form.
longSession true Keep grants in a long session: two weeks, no idle timeout. false keeps Kirby's normal session, which ends after 30 idle minutes.
title – Title of the login form. Replaces the translation, "Page locked" in English.
label.password – Label of the password field. Replaces the translation, "Password" in English.
label.submit – Label of the submit button. Replaces the translation, "Open page" in English.
error.password – Message after a wrong password. Replaces the translation, "The password is incorrect" in English.
error.csrf – Message when the CSRF token fails. Replaces the translation, "The CSRF token is invalid" in English.

Example config.php:

return [
    'johannschopplich.locked-pages' => [
        'slug' => 'geschuetzt',
        'title' => 'Geschützte Seite',
        'label' => [
            'password' => 'Kennwort',
            'submit' => 'Weiter'
        ],
        'error' => [
            'password' => 'Das Passwort ist nicht korrekt',
            'csrf' => 'Der CSRF-Token ist nicht korrekt'
        ]
    ]
];

Security Scope

This plugin gates the page a route returns and the files of locked pages – nothing else. Know its limits before relying on it:

  • Thumbs of locked files live in the cache root, site/cache/locked-pages/ by default. Kirby's .htaccess blocks it like content/ – on another web server, or with a cache root inside the document root, block it yourself.
  • A lock set outside the Panel leaves earlier media copies public. Kirby's media folder keeps the files requested while the page was open, until an editor saves the page in the Panel or a template outputs a URL of one of its files. After upgrading from an earlier version, save every locked page in the Panel.
  • The plugin takes over the file::url and file::version components. A plugin that registers them too, such as a CDN or image service plugin, conflicts with it, and the one Kirby loads last wins. If the other one wins, files of locked pages break or bypass the lock, depending on where it serves them from. If this one wins, the other one no longer applies to any file.
  • A route that renders a page itself is not gated. Return the page object from a custom route instead of $page->render(), or check Guard::isLocked($page) first.
  • Passwords are stored in plaintext in the page's content file, as an editor-visible shared secret. Treat a locked page as hidden from casual visitors, not as a vault.
  • Password attempts are not limited. Choose a long password, or rate-limit the form's URL at the web server.
  • Grants live as long as the session. Kirby renews the session while the visitor keeps coming back, so with the default long session a grant ends one to two weeks after the last visit. Shorten it with longSession => false, or clear grants through the logout hook.
  • Saving a translation drops its own lock. Kirby removes untranslatable fields from a translation when it saves one, so a page locked in a translation only becomes public once an editor saves that translation in the Panel. After upgrading from an earlier version, set the toggle and the password in the default language of every page locked in a translation.
  • The session is shared with the Panel. Kirby keeps one session per browser, so with longSession on, unlocking a page also turns a Panel login in the same browser into a two-week session without idle timeout.

Credits

Inspired by kirby-securedpages.

License

MIT License © 2021-PRESENT Johann Schopplich