Unique IDs & Permalinks

What are UUIDs?

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 this:

for a page: page://Eesj89FnbMzMMvs0.
for a file: file://nuvOLvWZZZWPSqxM,
for a user: user://yB6pFotK

Other than file paths, UUIDs never change. They are randomly generated when the model gets first created (via the Panel or programmatically).

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 or files won't break when the folder structure changes.

Kirby content can be produced via the Panel, or manually in the file system via a text editor. When you duplicate a page and its files via the Panel, a new UUID will be generated for those copied elements. If you duplicate a page folder manually in the filesystem, however, you need to remove existing UUIDs, and either manually or programmatically add new ones, or let Kirby automatically create one the next time you open those pages or files in the Panel.

How to use them

UUIDs are supported throughout the system wherever a model gets selected or queried.

In picker fields

The files, pages and 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 store property).

Let's consider an example blueprint with various picker fields:

The resulting content file will look like this:

Cover: file://VYnAL00UhvmOxq8J
----
Author: user://e1UrRWjqFRiu7mWg
----
Related:

- page://hb38HvnQfm8HlQ6e
- page://jchKH3EufbjC37KR
- page://jb8i1Sl6cOQOdOE8

In option fields

Option fields can also be configured to store the UUIDs, much like the picker fields:

venue:
  type: select
  options:
    type: query
    query: page('venues').children
    value: "{{ page.uuid }}"

In your templates

All of Kirby's PHP methods and helpers support querying by UUID. This includes:

Helper functions such as page() and url()
Field methods such as ->toFiles(), ->toPages() and ->toUsers()
Collection methods like $pages->find()

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 page://).

Permanent URLs

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 https://example.com/@/page/hb38HvnQfm8HlQ6e.

You can access the permalink with the $model->permalink() method:

<a href="<?= $page->permalink() ?>">Permalink</a>

Config settings

You can modify the UUID format or completely disable UUIDs using the content.uuid option in the config file.