About the docs

Parts of the documentation

This documentation has three four parts:

1. Guide:

That's where you currently are and where you should start when you are new to Kirby to get an overview on the system.

The Guide starts with the most basic topics like installation, introduction to the Starterkit, content, templating and blueprints, and continues with more advanced stuff. It explains general concepts, contains basic examples and links to related documentation in the Reference or Cookbook.

2. Reference

The Reference lists all classes, their methods and arguments in Kirby, as well as all the details about blueprint settings, available extensions and the REST API.

It also has examples for the most important everyday methods, and we keep adding more.

A large part of the Reference (all classes and their methods) is created automatically from the source code so that it is always complete and up-to-date. These automatically generated pages are then enriched with manually added examples. See details below.

3. Cookbook

The Cookbook is a growing collection of step-by-step recipes, categorized into several topics. These recipes can be short or extensive, depending on the subject they cover. Most recipes are written by the team, but you are invited to contribute your own knowledge. We try to link from the Cookbook to the relevant parts of the other docs and vice-versa where appropriate.

4. Search

The search can be accessed via the button at the top right of each page or with the keyboard shortcut Ctrl/Cmd+K. The dropdown allows you to filter the search results by parts of the documentation:

A Reference page in detail

Let's look at a detailed Reference page to see how you can get the most of it.

1. Method name: In our example, the method name is thumb().
2. Brief explanation what the method does: The thumb() method creates a thumbnail or modified version of the file.
3. A link to the Guide where available that puts the method into a larger context. Here, the link points to the Resizing & cropping images guide page.
4. Link to the source code on GitHub. If a method doesn't have in-depth explanations or examples, it can help to take a look at the source code. This is also useful if you want to modify a method in a model, for example.
5. Method signature, i.e. method name, accepted parameters and data types of these parameters
6. Parameters the methods accepts/expects together with their allowed types, see parameters
7. Return type. If the return type is a Kirby class, this will be a link to the corresponding class, see below
8. Exceptions: type of exception thrown by the method with link to the Exception class, see exceptions. Exceptions are not always indicated!
9. Parent class: The current method is a member method of this class, here thumb() is a member method of the Kirby\Cms\File class.
10. Parameter details, particularly if a method parameter accepts an array
11. Example(s). If present, a typical usage example for the method with some context.

Not all of the above features may be present in each method description. Less used methods or those that have mostly internal relevance often don't have examples (yet).

Parameters

Many methods accept or require one or more parameters. These parameters need to be of a given data type (string, array, bool, null, object etc.), see return types below. If you pass a data type that is not allowed, PHP will complain with a TypeError.

For a list of all available data types in PHP see also: Data types in PHP

Particularly when the expected parameter is of type array, you need to know which key/value pairs are expected within this array.

Our example thumb() method is a good example for a method which accepts different data types for the only parameter. So let's look at this more closely. The $options parameter can have one of the following types:

1. Null, or no parameter: If you don't pass a parameter, the default preset from the configuration will be used.
2. String: If you pass a string, this string must refer to a named preset in your configuration.
3. Array: If you pass an array, this array can contain one or more of the key/value pairs described under "Options".

Return types

Next to the parameters, the return type is of utmost importance, because it signals to you what kind of data type a method returns, and therefore what you can do with the result of calling this method.

Strings

If a method returns a simple string, you can for example echo it, or use it in other contexts where a string is required as input:

<?= $page->url() ?>

Booleans

Many methods return a boolean (bool), i.e. if something is true or false:

<?php
$bool = $page->hasChildren();
var_dump($bool);

Such methods are usually used in conjunction with an if-statement (or a ternary operator)

<?php if ($page->hasChildren()): ?>
<!-- do stuff -->
<?php endif ?>

Numbers

PHP knows two types of numbers:

• integer (int) and
• floating point numbers (float)

Example for method which returns an integer:

<?php
$count = A::count([15, 19, 105, 7]);
var_dump($count); //int(4)

Example for method which returns a floating point number:

<?php
$result = A::average([15, 19, 105, 7], 2);
dump($result); //float(36.5)

Arrays

If a method returns an array, you can loop through the elements of the array…

<?php $contentArray = $page->readContent(); ?>
<dl>
<?php foreach ($contentArray as $fieldName => $value): ?>
  <dt><?= $fieldName ?></dt>
  <dd><?= $value ?></dd>
<?php endforeach ?>
</dl>

…or just dump it to view its structure:

<?php
$contentArray = $page->readContent();
dump($contentArray);

Objects

Methods can also return objects. In the Kirby context these will mainly be Kirby objects, either of the parent class of the method, or another Kirby class (Field, Content, Page, Pages, Structure, to name just a few). If a method returns an object, you have access to the methods of this class. Sounds theoretical? Let's consider some examples.

A typical thing you will do in Kirby is to fetch a particular page by its id:

<?php $p = $site->find('blog') ?>

The return type of this method will be a an object of the Kirby\Cms\Page class if the page exists. And this Page class has a number of methods, which you can find here.

That means, you can call any of the methods listed on that page on the return value of this method:

<?php if ($p = $site->find('blog')): ?>
  <a href="<?= $p->url() ?>"><?= $p->title() ?></a>>
<?php endif ?>

If we return to our Reference example, the $file->thumb() method, we see that it can return two types of objects:

1. A Kirby\Cms\FileVersion object
2. A Kirby\Cms\File object, i.e a new instance of the original class

The second return type is basically returned if you don't pass an argument and there is not default preset defined, or if you pass a string as argument and a preset of this name doesn't exist.

In any case, you can follow the return type links to find out what methods you can call on the return type. In most cases, you will probably use the url() method:

<?= $file->thumb()->url() ?>

Void

This return type applies when a method doesn't return anything. Typical examples for such methods are class setter methods, but of course also other methods, for example:

<?php
$kirby->user()->logout();

Exceptions

If a method can throw an exception, you must be particularly careful, and wrap this method in a try/catch block, otherwise calling this method can break your site.

<?php
  try {
    $kirby->impersonate('kirby');
    $page->update([
      'title' => 'New title',
      'text'  => 'Let\'s update this text',
    ]);
  } catch (LogicException|InvalidArgumentException $e) {
    // do something here if an exception is thrown;
    // what you do is essentially up to you and depends on the context
    echo 'An error occurred: ' . $e->getMessage();
  }

And with this, we hope you can get the most out of our documentation.

Missing something?

If you miss examples for a specific method or class, or run into any other issues with the documentation, please create an issue in the getkirby.com repo on GitHub. The more specific you are when reporting your issue, the more actionable it is and the easier it becomes to fix the issue.