Configuration
The config.php
General Kirby configuration settings and configuration settings for plugins go into /site/config/config.php
. The config file contains a return statement with an array of config options.
<?php
return [
'debug' => true,
'someOtherSetting' => 'something'
];
If you want to keep your config.php
clean when using more complex options, you can outsource them to individual files that you require in the return array:
return [
'debug' => true,
'hooks' => require_once 'hooks.php'
];
return [
// your hooks
];
Using options
Config options can be used anywhere in Kirby with the $kirby->option()
method:
$kirby->option('someOtherSetting');
Or with the option
helper:
option('someOtherSetting');
Fallbacks
You can pass option fallbacks as second parameter in the option methods. This can be useful if a option does not necessarily have to be set in the config file.
$kirby->option('someOtherSetting', 'my fallback');
option('someOtherOption', 'my fallback');
All configuration options
api
Set options for Kirby's REST API
auth
Set options for login via the Panel and the API
cache
Enables/disables Kirby's cache and sets cache options
content
Set how Kirby handles content
date
Setup date handling
debug
Enables/disables PHP errors
Set options for Kirby's built-in email class
error
The name of the error page folder
fatal
Custom fatal view that is shown if there's a PHP error
home
Set the name of the home page folder
hooks
Hook into Kirby events and execute your functions in the background
kirbytext
Configure the behavior of KirbyText and particular tags
languages
Enables language definitions via the Panel
locale
Sets the global locale setting for PHP
markdown
Options for the Markdown parser
panel
Options for the Panel
ready
Inject last minute configuration options
remote
Overrides the defaults for requests to remote servers
routes
Additional route setup for Kirby's internal router
servers
Defines the supported web servers
session
Configuration settings for Kirby sessions
slugs
Set language for slug generator
smartypants
Convert typical text formatting issues into a typographically correct version
thumbs
Set default configuration for thumbs
url
Set the base URL for the site.
whoops
Enables/disables the Whoops debugger
Hooks and Routes
You can register hooks or routes in your config.php
if you don't want to create a plugin for them.
<?php
return [
'hooks' => [
// the hooks definition goes here…
],
'routes' => [
// the routes definition goes here…
]
];
All hooks
file.changeName:before
$file, $name
file.changeName:after
$newFile, $oldFile
file.changeSort:before
$file, $position
file.changeSort:after
$newFile, $oldFile
file.create:before
$file, $upload
file.create:after
$file
file.delete:before
$file
file.delete:after
$status, $file
file.replace:before
$file, $upload
file.replace:after
$newFile, $oldFile
file.update:before
$file, $values, $strings
file.update:after
$newFile, $oldFile
kirbytags:before
$text, $data, $options
kirbytags:after
$text, $data, $options
kirbytext:before
$text
kirbytext:after
$text
page.changeNum:before
$page, $num
page.changeNum:after
$newPage, $oldPage
page.changeSlug:before
$page, $slug, $languageCode
page.changeSlug:after
$newPage, $oldPage
page.changeStatus:before
$page, $status, $position
page.changeStatus:after
$newPage, $oldPage
page.changeTemplate:before
$page, $template
page.changeTemplate:after
$newPage, $oldPage
page.changeTitle:before
$page, $title, $languageCode
page.changeTitle:after
$newPage, $oldPage
page.create:before
$page, $input
page.create:after
$page
page.delete:before
$page, $force
page.delete:after
$status, $page
page.duplicate:before
$originalPage, $input, $options
page.duplicate:after
$duplicatePage, $originalPage
page.update:before
$page, $values, $strings
page.update:after
$newPage, $oldPage
route:before
$route, $path, $method
route:after
$route, $path, $method, $result, $final
site.changeTitle:before
$site, $title, $languageCode
site.changeTitle:after
$newSite, $oldSite
site.update:before
$site, $values, $strings
site.update:after
$newSite, $oldSite
user.changeEmail:before
$user, $email
user.changeEmail:after
$newUser, $oldUser
user.changeLanguage:before
$user, $language
user.changeLanguage:after
$newUser, $oldUser
user.changeName:before
$user, $name
user.changeName:after
$newUser, $oldUser
user.changePassword:before
$user, $password
user.changePassword:after
$newUser, $oldUser
user.changeRole:before
$user, $role
user.changeRole:after
$newUser, $oldUser
user.create:before
$user, $input
user.create:after
$user
user.delete:before
$user
user.delete:after
$status, $user
user.login:before
$user, $session
user.login:after
$user, $session
user.logout:before
$user, $session
user.logout:after
$user, $session
user.update:before
$user, $values, $strings
user.update:after
$newUser, $oldUser
system.loadPlugins:after
Multi-environment setup
You can set different options based on the domain by adding additional config files containing the domain.
Example setup
- /site/config/config.localhost.php
- /site/config/config.staging.yourdomain.com.php
- /site/config/config.yourdomain.com.php
- /site/config/config.www.yourdomain.com.php
By setting different options in those config files, you get a very flexible system that can be deployed to different servers and react to the current environment accordingly.
Custom folder setup
Kirby lets you adjust its default folder setup. Every path to a system-relevant directory is called root in Kirby. All roots can be configured when Kirby is initialized, which normally happens in your index.php
.
Here is an example in which the site and content folders are renamed.
<?php
include __DIR__ . '/kirby/bootstrap.php';
$kirby = new Kirby([
'roots' => [
'index' => __DIR__,
'site' => __DIR__ . '/project',
'content' => __DIR__ . '/data'
]
]);
echo $kirby->render();
All configurable roots
$kirby->root('accounts')
Returns the root of the accounts folder.
$kirby->root('assets')
Returns the root of the assets folder.
$kirby->root('blueprints')
Returns the root of the blueprints folder
$kirby->root('cache')
Returns the root of the cache folder.
$kirby->root('collections')
The directory where all your shared collections are stored.
$kirby->root('config')
Returns the root of the config folder.
$kirby->root('content')
Returns the root of the content folder
$kirby->root('controllers')
Returns the root of the controllers folder.
$kirby->root('index')
Returns the document root of the website
$kirby->root('kirby')
Returns the root of the Kirby core folder
$kirby->root('logs')
Returns the root of the logs file folder.
$kirby->root('media')
Returns the root of the media folder.
$kirby->root('models')
Returns the root of the models folder.
$kirby->root('plugins')
Returns the root of the plugins folder.
$kirby->root('roles')
Returns the root of the roles folder.
$kirby->root('sessions')
The storage folder for all session files
$kirby->root('site')
Returns the root of the site folder
$kirby->root('snippets')
Returns the root of the snippets folder.
$kirby->root('templates')
Returns the root of the templates folder.
Public folder setup
In our Starterkit, we offer a flat setup that installs all folders directly in the document root of your server. This is not always the best solution, but it's the solution that is most compatible with all types of hosting.
A typical setup for secure, modern web applications has every private folder behind the document root and the domain points to a public folder with the index.php
and additional public assets like CSS files, images, etc.
index.php
The key to this setup is the index.php
in the public
folder:
<?php
include __DIR__ . '/../vendor/autoload.php';
$kirby = new Kirby([
'roots' => [
'index' => __DIR__,
'base' => $base = dirname(__DIR__),
'content' => $base . '/content',
'site' => $base . '/site',
'storage' => $storage = $base . '/storage',
'accounts' => $storage . '/accounts',
'cache' => $storage . '/cache',
'sessions' => $storage . '/sessions',
]
]);
echo $kirby->render();
Shared storage folder
This example does not only use a public folder setup, it also places accounts, cache and sessions folders in a shared storage folder. This can be a useful pattern to keep track of those additional folders that need to be writable by Kirby.
Custom URL setup
If you want to serve media and assets from other domains than your main domain, you can define custom URLs for all public facing folders.
This allows you to store your media or assets in other locations on your server or even on a CDN.
Your custom URLs can be configured when Kirby is initialized, which normally happens in your index.php
. In the example below, custom URLs are set for the media
and assets
folders:
<?php
include __DIR__ . '/kirby/bootstrap.php';
$kirby = new Kirby([
'urls' => [
'index' => 'https://getkirby.com',
'media' => 'https://media.getkirby.com',
'assets' => 'https://assets.getkirby.com',
]
]);
echo $kirby->render();
All configurable URLs
$kirby->url('assets')
Returns the url of the assets folder
$kirby->url('index')
Returns the base url of the site
$kirby->url('media')
Returns the URL of the media folder
Panel configuration
The Panel has additional configuration options to include custom CSS and JS files, to move it to a different subfolder or to switch it off entirely.