There are already a lot of ways you can customize Kirby by adding custom methods, overwrite core components, extend the Page class with your own model, and a whole lot more.
But there are also situations where you might want to overwrite certain parts of the core classes for which there is no existing extension yet. For example, to create virtual pages as children of the
Site object or virtual users, or to simply add new methods to those classes.
In this recipe, we will explore how we can achieve this.
Since we are touching core functionality here, make sure you understand what you are doing and how it might affect other parts of the code, so as not to break anything.
- Kirby Starterkit or Plainkit
- Basic understanding of Object Oriented Programming is helpful but not required. Also see link at the end of this recipe.
- Create new class in a plugin
- Replace Kirby with new class in your project's main
Let's start with the first step. Create a new plugin folder, e.g.,
/site/plugins with the obligatory
Inside this new plugin folder, create a folder called
classes and then inside this
/classes folder a new file,
CustomKirby.php, so that our file structure looks like this:
CustomKirby.php file, we create the new class:
To make our installation use the new class, we have to replace the
Kirby class with our
CustomKirby class in the
index.php file at the root of our installation:
And that's it. Let's do a quick test. If you head over to a template and…
…you will see that
$kirby now refers to our new
This new class inherits all methods and properties from the parent
Kirby\Cms\App class, so at this point, this doesn't really impact Kirby's functionality at all yet.
We can now start extending our new class, for example with a custom method:
Back in our template, when we now use the new method
it will print
Hello world as expected. Cool, we have extended the parent class with new custom functionality, however basic the example actually is.
As above, we first create a custom Site class skeleton inside the
Then we register the class in our plugin's
index.php, so it gets loaded when requested:
With this in place, we are ready to replace the
Site object in the above-mentioned two methods with our
You can verify this works by dumping
in a template.
We are now ready to add custom methods to the
CustomSite class or overwrite existing ones.
If you landed here, you are probably familiar with how you can add virtual pages from a database or other data source in Kirby by creating a Page model and overwriting the
children() method. The virtual children in these examples are always children of a given page that actually exists as a folder in your file system.
But let's assume you wanted to add virtual pages as children of the Site object. Well, now you can. Let's try.
CustomSite class, let's add a
Visit those pages in your browser to check if it works as expected. Since we haven't created any specific templates yet, the
default.php template will be used to output the content of those pages at the moment.
In the example above, we created the
$pages array manually, but the data for these pages can also come from an API or database like in the virtual pages guide examples mentioned above.
This intro should put you into a good starting position to explore yourself what you can do with it. Whenever you have questions, let's discuss them on the forum