johannschopplich / kirby-locked-pages
Password-protect pages for Kirby CMS
Package info
github.com/johannschopplich/kirby-locked-pages
Type:kirby-plugin
pkg:composer/johannschopplich/kirby-locked-pages
Fund package maintenance!
Requires
- php: >=8.2
- getkirby/composer-installer: ^1
Requires (Dev)
- getkirby/cms: ^5 || ^6
- phpunit/phpunit: ^12
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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, otherwisefalse.$passwordLabel: the label of the password field, from thelabel.passwordoption or the translation.$submitLabel: the label of the submit button, from thelabel.submitoption or the translation.$page: the login page, not the locked one – itstitle()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.htaccessblocks it likecontent/– on another web server, or with acacheroot 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::urlandfile::versioncomponents. 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 checkGuard::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
longSessionon, 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