---
title: "Field Methods"
description: "Resolve UUIDs in blocks, layouts, and permalinks server-side – frontends consume ready-to-use URLs and IDs."
canonical_url: "https://kirby.tools/docs/headless/usage/field-methods"
---

# Field Methods

> Resolve UUIDs in blocks, layouts, and permalinks server-side – frontends consume ready-to-use URLs and IDs.

## `toResolvedBlocks()`

The `toResolvedBlocks()` method extends Kirby's [`toBlocks()`](https://getkirby.com/docs/reference/templates/field-methods/to-blocks) method by resolving UUIDs to file and page objects. This eliminates the need to resolve UUIDs in your frontend application.

### Before and After

Using Kirby's default `toBlocks()` method returns UUIDs:

```json
{
  "content": {
    "image": ["file://BYXR0pvumEbfTknP"],
    "alt": "Staring at stars"
  },
  "id": "a1c0f653-2e36-4b07-a7fa-d22ef27dd114",
  "isHidden": false,
  "type": "image"
}
```

Using `toResolvedBlocks()` resolves UUIDs to complete file objects:

```json
{
  "content": {
    "alt": "Staring at stars",
    "image": [
      {
        "url": "http://example.com/media/pages/notes/image.jpg",
        "width": 1024,
        "height": 683,
        "srcset": "http://example.com/media/pages/notes/image-300x.jpg 300w, http://example.com/media/pages/notes/image-1024x.jpg 1024w",
        "alt": "Staring at stars"
      }
    ]
  },
  "id": "a1c0f653-2e36-4b07-a7fa-d22ef27dd114",
  "isHidden": false,
  "type": "image"
}
```

### Files Resolver

Out of the box, one entry is configured: the `image` field of Kirby's `image` block – which is what the example above resolves. Configure the option to reach other blocks:

```php [config.php]
return [
    'blocksResolver' => [
        'files' => [
            // Keep Kirby's `image` block resolving
            'image' => 'image',
            // Resolve the `image` field in the `gallery` block
            'gallery' => ['image'],
            // Resolve multiple fields
            'hero' => ['background', 'thumbnail']
        ]
    ]
];
```

<warning>

The option replaces the built-in list rather than extending it. Leave `'image' => 'image'` out and Kirby's own image block stops resolving, which is easy to miss – the block keeps rendering, it just hands the frontend a `file://` UUID again.

</warning>

The default file resolver returns:

```php [config.php]
return [
    'blocksResolver' => [
        'defaultResolvers' => [
            'files' => fn (\Kirby\Cms\File $file) => [
                'url' => $file->url(),
                'width' => $file->width(),
                'height' => $file->height(),
                'srcset' => $file->srcset(),
                'alt' => $file->alt()->value()
            ]
        ]
    ]
];
```

Set the same option to your own closure to change which keys a resolved file carries.

### Pages Resolver

Configure which page fields to resolve in your blocks:

```php [config.php]
return [
    'blocksResolver' => [
        'pages' => [
            // Resolve the `link` field in the `cta` block
            'cta' => ['link'],
            // Resolve multiple fields
            'references' => ['related', 'author']
        ]
    ]
];
```

The default page resolver returns:

```php [config.php]
return [
    'blocksResolver' => [
        'defaultResolvers' => [
            'pages' => fn (\Kirby\Cms\Page $page) => [
                'uri' => $page->uri(),
                'title' => $page->title()->value()
            ]
        ]
    ]
];
```

### Custom Resolvers

Define custom resolvers for specific fields in specific blocks using the `{blockName}:{fieldName}` syntax:

```php [config.php]
use Kirby\Cms\Block;
use Kirby\Content\Field;

return [
    'blocksResolver' => [
        'resolvers' => [
            // Resolve the `link` field in the `intro` block
            'intro:link' => fn (Field $field, Block $block) => [
                'value' => $field->value(),
                'uri' => $field->toPage()?->uri()
            ],
            // Resolve KirbyText in the `text` field of the `note` block
            'note:text' => fn (Field $field, Block $block) =>
                $field->kirbytext()->value(),
            // Resolve structure field
            'testimonial:author' => fn (Field $field, Block $block) =>
                $field->toStructure()->first()?->toArray()
        ]
    ]
];
```

### Resolved Key

By default, resolved fields replace the original field values. To keep both original and resolved values, configure a `resolvedKey`:

```php [config.php]
return [
    'blocksResolver' => [
        'resolvedKey' => 'resolved'
    ]
];
```

This stores resolved content in a separate key:

```json
{
  "content": {
    "alt": "Staring at stars",
    "image": ["file://BYXR0pvumEbfTknP"],
    "resolved": {
      "image": [
        {
          "url": "http://example.com/media/pages/notes/image.jpg",
          "width": 1024,
          "height": 683,
          "srcset": "http://example.com/media/pages/notes/image-300x.jpg 300w, http://example.com/media/pages/notes/image-1024x.jpg 1024w",
          "alt": "Staring at stars"
        }
      ]
    }
  },
  "id": "a1c0f653-2e36-4b07-a7fa-d22ef27dd114",
  "isHidden": false,
  "type": "image"
}
```

## `toResolvedLayouts()`

The `toResolvedLayouts()` method extends Kirby's [`toLayouts()`](https://getkirby.com/docs/reference/templates/field-methods/to-layouts) method. It uses `toResolvedBlocks()` under the hood, so all block resolver configurations apply.

```php [site/templates/default.php]
<?php

$data = [
    'title' => $page->title()->value(),
    'layout' => $page->layout()->toResolvedLayouts()->toArray()
];

echo \Kirby\Data\Json::encode($data);
```

## `resolvePermalinks()`

The `resolvePermalinks()` method resolves page and file permalinks in `href` and `src` attributes. This is useful for writer fields containing permalink URLs like `/@/page/nDvVIAwDBph4uOpm`.

<note>

This method works the same as Kirby's built-in `permalinksToUrls()` method, but supports a custom URL parser.

</note>

### Basic Usage

```php
use Kirby\Cms\Page;

return [
    'query' => 'page("home")',
    'select' => [
        'title' => true,
        'text' => fn (Page $page) => $page->text()->resolvePermalinks()
    ]
];
```

### Custom URL Parser

For headless setups, you may want to remove the origin or language prefix from URLs:

```php [config.php]
return [
    'permalinksResolver' => [
        // Strip the origin from URLs
        'urlParser' => function (string $url, \Kirby\Cms\App $kirby) {
            return parse_url($url, PHP_URL_PATH);
        }
    ]
];
```

For multi-language sites, remove language prefixes:

```php [config.php]
return [
    'permalinksResolver' => [
        'urlParser' => function (string $url, \Kirby\Cms\App $kirby) {
            $path = parse_url($url, PHP_URL_PATH);

            // Strip language prefix for German URLs
            if (str_starts_with($path, '/de')) {
                return substr($path, 3);
            }

            return $path;
        }
    ]
];
```

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>