The first example requires at least Kirby 3.6.2, while the second example works with 3.6.x and higher.
To implement a (frontend) user registration in your Kirby project, you can leverage Kirby's authentication features. To achieve this, we are going to implement the following steps:
- Enable login via code in Kirby's config
- Create a new user when user submits registration form
- Send an authentication challenge once new user is created
- Redirect the user to the Panel login or a frontend login page
- Verify code and log user in
This recipe is based on the Kirby Starterkit. Feel free to use a Plainkit or your own project to follow along, though.
Ready? Let's start with the config settings!
To test locally whether sending the login code via email works, you can use MailHog or a similar tool.
In our first example, we will let the Panel handle the login code verification, and add a login page in the second example, where we handle everything on the frontend.
To handle user registrations, we create a registration page as
/registration/registration.txt in the
/content folder with a title and optional other information you want to render on the page:
Our newly registered users should get the role of
client with no Panel access. We therefore create the following
Change permissions or the home option as required. For our example, we don't want to allow Panel access and send the user directly to the home page after login.
If you like, you could allow this role access to their own user account in the Panel, while keeping all other areas locked.
In its most minimal form, our registration template would just have a form with an
The controller handles our form validation and, on successful user creation, redirects the new user to the Panel login page. Find the different steps explained in the comments:
With the page all set, we are ready for some testing. Make sure you are logged out of the Panel. Open the
registration page at
example.com/registration and enter an email address. You should be redirected to the Panel login page with the code form field.
Once you enter the login code you received via email in the form field, you are logged in and automatically redirected to the location set via the
home option in the
Great, we now have a working user registration page with very little code.
While Kirby limits automatic registrations from the same IP (you can set the limit in your
config.php), consider using some sort of spam protection in a production environment (honeypot, captcha etc. ).
If you want to handle everything on the frontend instead of sending the user to the Panel login page for authentication, you could instead redirect the user to an authentication page. In the next steps, we will look into this option.
For our second example, we have to adapt our code from above a little and then add a login page.
But let's first change the redirect link in the
registration.php controller from…
and create a new
login page with a content file called
The login page serves two purposes:
- Get a user email and send an authentication challenge if there is no valid challenge
- Get and validate the authentication code if a challenge is active
In the next two steps, we create the template and controller for the
In the template, we create the login form. Depending on the current authentication status (
inactive, see controller below), the form shows either the
code or the
active auth status are already logged in and therefore redirected.
The general procedure is therefore the same as in our first example above.
login.php controller is a bit more complex because depending on which field is submitted via the form, we either validate the provided code or send an new authentication challenge. Again I have explained all steps in the comments.
Time for testing. Clear the sessions folder to make sure you don't have an active sessions anymore. Register a new user. You should now land on the new login page. Enter the code in the form field and the new user should be logged in again.
By now, we have created the following files in the project:
Currently, we have to access all pages via the browser's address bar. Let's make it more comfortable, and add links to the
login pages in the navigation, and also add a logout link for logged-in users.
To this purpose, we extend the navigation item in the header snippet as follows:
And additionally, add a logout route in your
Currently, the login and registration pages will be opened in the Panel with the
default.yml blueprint. As long as we don't need specific fields in those pages, that's totally fine. Feel free to add blueprints for these pages as you see fit.
In many cases, we want to redirect the user to the location where they left off before they hit the registration/login page. For this purpose, we are going to store the original page in the session.
The first step is to add the current page id as parameter to the navigation links. And while we are at it, we can do the same for the logout link.
We create a site method that allows us to fetch the referrer value from the session, so that we can easily retrieve that value in our code. for this purpose, we create a little plugin in the
If a value is stored in the session, we return this value, otherwise we redirect to the home page.
We can now use this method in the
client.yml user blueprint to set the
home option dynamically.
At the top of the
registration controller we fetch the
referrer parameter and store it in the session. We also use the referrer value to redirect already logged-in users.
We also have to fix the redirect link to the login page and add the original referrer as parameter:
We also check if the parameter is set in the
And replace the two instances of hard-coded redirects to the home page with
That was it. Happy coding!