The Kirby “config” File

An unremarkable litte “config.php” file lives in the site/config directory. However, it offers a handful of very interesting settings for us.

Caching

With Kirby, we’re already using a very speedy and lightweight CMS - mainly because it doesn’t use a database and instead fully relies on simple flat files. However, we can further boost the performance by activating Kirby’s caching mechanism in config.php:

c::set('cache', true);
c::set('cache.ignore', array(‘search’, ‘other-dynamic-page’));

With the first statement, we switch the caching on. Additionally, we could choose between three different caching mechanisms that Kirby offers: Memcached, APC, and simple flat files.

We’ll go with the latter, default one: Kirby will write the cached content in “site/cache” as each page is requested for the first time. Make sure this directory is writable; and simply delete its contents if you want to invalidate / reset the cached content.

The second directive (‘cache.ignore’) is especially important because it tells Kirby which pages not to cache. This is crucial if you have dynamic pages, e.g. a search page or a newsletter script. If you would cache these pages, you would run the risk of breaking these dynamic parts - by always returning the same, cached response of a search query, for example.

In general, Kirby’s caching is both robust and powerful. For production sites, it is highly recommended to be turned on.

During development, however, you will not want to have caching turned on. Here’s a little tip on how to best achieve this using Git:

Using Git with Tower Command Line

The final, production directive should be committed to the repository - so, turn caching on and commit the changed config.php.

Afterwards, turn it off again in your code (by setting “cache” to “false”). But this time, don’t commit this because you want this setting only on your local machine. Instead, right-click the changed “config.php” file in Tower’s Working Copy and select “Mark —> Set Assume Unchanged”.

Marking a file as “assume unchanged” makes Git ignore any local changes in this file. But, in contrast to really “ignoring” a file, it doesn’t remove the file from version control: you can have a certain version of it committed in Git, but then decide to not track any further changes by setting the “assume unchanged” flag.

Read more about Marking Files as Assume-Unchanged in Tower’s documentation.

The final, production directive should be committed to the repository - so, turn caching on and commit the changed config.php.

Afterwards, turn it off again in your code (by setting “cache” to “false”). But this time, don’t commit this because you want this setting only on your local machine. Instead, set the “assume-unchanged” flag on this file with the following command:

git update-index --assume-unchanged site/config/config.php

Marking a file as “assume unchanged” makes Git ignore any local changes in this file. But, in contrast to really “ignoring” a file, it doesn’t remove the file from version control: you can have a certain version of it committed in Git, but then decide to not track any further changes by setting the “assume unchanged” flag.

Adding Custom Config Values

In many cases, it’s clever to keep certain values in a central configuration file. Especially when you need that value in multiple places; or simply because it’s cleaner to have all configuration values in a common place instead of spreading them all over your codebase.

Luckily, Kirby’s config file also supports custom, user-defined config values. Take a look at our list view as an example: we only show an excerpt of the post’s full text on the list. The number of characters we want to show is a perfect example for a custom setting in config.php:

c::set('teaser.newest', 200);
c::set('teaser.recent', 150);

We can then use this value in our templates:

$newestPost->text()->kirbytext()->excerpt(c::get('teaser.newest'))

If we ever decide to change the length of the excerpt texts, we can do this simply by changing a number in our config.

Other good examples of config values could be your Google Analytics ID, API keys and IDs for your newsletter service, or even Twitter handles that you need in multiple places.

Debug Mode

On a production server, you don’t want debug information like PHP errors to be visible. While you’re developing your site on your machine, however, it can be very helpful to see things like these in your browser. In Kirby, you can simply activate a “debug” mode in config.php:

c::set('debug', true);

Don’t forget to switch this off for your production server. You can choose the same workflow as for the cache setting (marking the file “assume-unchanged”).

More Config Options

Kirby offers tons of other configuration options. For a complete overview, see the official options documentation.

Before we move on to our next topic, one more config option might be worth mentioning:

c::set('license', 'put your license key here');

Kirby offers very affordable licenses for both personal and professional use. Please consider supporting the developer for the great work he’s doing.

Giveaways. Cheat Sheets. eBooks. Discounts.
And great content from our blog!

About Us

As the makers of Tower, the best Git client for Mac and Windows, we help over 100,000 users in companies like Apple, Google, Amazon, Twitter, and Ebay get the most out of Git.

Just like with Tower, our mission with this platform is to help people become better professionals.

That's why we provide our guides, videos, and cheat sheets (about version control with Git and lots of other topics) for free.