# Configuring Kirby
## The `config.php`
General Kirby configuration settings, configuration settings for plugins as well as custom configuration settings go into `/site/config/config.php`. The config file contains a return statement with an array of config options:
```php "/site/config/config.php"
true,
'someOtherSetting' => 'something'
];
```
Make sure to only use a single return statement in your `config.php` file (with all your options defined in that one return array).
Since Kirby is not being fully initialized yet when reading the configuration, you cannot use the `$kirby` object or `kirby()` helper in the `config.php`.
If you need to set options dynamically, you can use the `ready` option with a callback.
### Plugin options
You can also set options for your installed plugins in the `site/config/config.php`:
```php "/site/config/config.php"
[
'option' => 'a custom value',
'another-option' => [
'with-a-nested-option' => 'also a custom value'
]
]
];
```
Please use the exact syntax as in the example above, i.e. with the `author.pluginname` as a single string. The following example will ***not* work**:
```php "/site/config/config.php"
[
'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:
```php "/site/config/config.php"
return [
'debug' => true,
'hooks' => require_once 'hooks.php'
];
```
```php "/site/config/hooks.php"
return [
// your hooks
];
```
## Using options
Config options can be used anywhere in Kirby with the `$kirby->option()` method:
```php
$kirby->option('someOtherSetting');
```
Or with the `option` helper:
```php
option('someOtherSetting');
```
You can use dot notation to access nested config options:
```php "site/config/config.php"
return [
'my' => [
'option' => 'foo'
]
];
```
```php
$kirby->option('my.option')
```
### 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.
```php
$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 "/site/config/config.php"
[
// 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
[
'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
```filesystem
/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.
Note that the settings in the standard `config.php` file are always used. If you need different settings in another environment, you will have to override those settings in the domain specific configuration file (or only set those options in your domain specific config file).
General settings for all environments should be included in the standard `config.php` file to avoid code duplication.
### CLI configuration
If you are using Kirby with a command-line interface (or CLI for short), for example with the Kirby CLI or with a custom script, you can define specific config overrides in a separate file:
```filesystem
/site/config/config.cli.php
```
The CLI-specific config file works like a host-specific config file in that it can override anything you put into your standard `config.php`.
### 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:
```filesystem
/site/config/env.php
```
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.
The `env.php` file is loaded before any host-specific config files. If `env.php` sets or overrides the `url` option, it will control which host-specific config file gets loaded. However in the end result, the options defined in `env.php` will always override any other configuration file.
## 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.