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'
];

Plugin options

You can also set options for your installed plugins in the site/config/config.php:

<?php

return [
    'author.pluginname' => [
        'option' => 'a custom value',
        'another-option' => [
            'with-a-nested-option' => 'also a custom value'
        ]
    ]
];

<?php

return [
    'author' => [
        'pluginname' => [
            'option' => 'a custom value',
            'another-option' => [
                'with-a-nested-option' => 'also a custom value'
            ]
        ]
    ]
];

Using multiple config files

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

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

Base URL setup

By default, Kirby detects the base URL of your installation from the server configuration. This base URL is then used to generate all resource URLs and links on your site and in the Panel.

If your URLs are incorrect, this may be because of a reverse proxy that sits in between the client and Kirby. For security reasons, the reverse proxy configuration is only respected if you explicitly configure a fixed base URL or a set of possible base URLs with the url option:

<?php

return [
  'url' => [
    'https://example.com',
    'https://staging.example.com',
    'http://example.test'
  ]
];

You can read more in the reference.

Multi-environment setup

You can set different options based on the domain by adding additional config files containing the domain.

Example setup

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.

Deployment configuration

There is another optional config file that overrides any option value, no matter if it was set in config.php or a host-specific config file:

You can use this file for dynamic option values that are set during a deployment, e.g. a specific fixed url value for that server, randomly generated deployment IDs or sensitive data like API keys.

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

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__ . '/../kirby/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

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.