Kirby is built on just files and folders, which is great for flexibility in structuring your content, performance and rapid development. Referring to a page or file from elsewhere by its file path works, but makes the site structure pretty rigid and takes away a lot of the flexibility of the content structure. Because as soon as a page or file gets renamed or moved, its file path changes – and immediately the reference to it will break.
UUIDs (universally unique identifiers) are an additional way to refer to any model in Kirby – be it a page, a file or a user. UUIDs look something like
page://Eesj89FnbMzMMvs0. In contrast to file paths, UUIDs never change. They are randomly generated when the model gets first created. It is so unlikely that two models ever share the same UUID that they can be considered unique (in fact, it will take millions of years to reach a 1% probability of a collision on any given site). These properties make UUIDs the ideal candidate for robust and persistent references.
UUIDs can be used in many parts of the system to identify a specific page, file or user. When using a UUID for your reference, those ties to other pages won't break when the folder structure changes.
Native support for UUIDs was released with Kirby 3.8.
UUIDs are supported throughout the system wherever a model gets selected or queried.
users fields support UUIDs out of the box. Every page or file that you select will be referenced by its UUID automatically (unless you disable the UUID mode with the field's
Let's consider an example blueprint with various picker fields:
The resulting content file will look like this:
Option fields can also be configured to store the UUIDs, much like the picker fields:
All of Kirby's PHP methods and helpers support querying by UUID. This includes:
- Helper functions such as
- Field methods such as
- Collection methods like
Kirby will handle the lookup for you. It will also automatically detect if you are passing a file path or UUID (every UUID starts with a URI protocol like
Because UUIDs never change and are unique across the site, they are perfect for permanent shortlinks (permalinks) that can be used for sharing.
The path of permalinks in Kirby always begins with the
@ sign, for example
You can access the permalink with the