# Kirby Ink - PHP Class-based Blueprints

**URL:** <https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088>\
**Category:** Questions\
**Tags:** v4\
**Created:** [November 24, 2023, 11:55am UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088 "2023-11-24T11:55:19Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\
**Post date:** [November 24, 2023, 11:55am UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/1 "2023-11-24T11:55:19Z")

</div>

> I am creating posts for [my plugins](https://getkirby.com/plugins/bnomei) to make it easier to find them using the forum search and not just the docs search.

* * *

> **[GitHub - bnomei/kirby-blueprints: Kirby Ink - PHP Class based Blueprints for Kirby...](https://github.com/bnomei/kirby-blueprints)**
>
> Kirby Ink - PHP Class based Blueprints for Kirby CMS

This plugin introduces two new ways to define blueprints for Kirby 4. (yes 4+ only)

## Fluent & Named Helper Classes

Define blueprints in PHP files with the fluent definition or named parameter definition instead of just the array definition that Kirby provides. You can use the\*::make()-helpers to create them and avoid typos.

**site/plugins/example/blueprints/fields/description.php**

```php
return Field::make(FieldTypes::TEXTAREA)
    ->label('Description')
    ->toArray();

```

## PHP Attributes for PageModels

Define blueprints for pages in PageModels and use public properties with PHP attributes to define fields. You will gain auto-completion and insights on hover for the fields in your templates.

**site/plugins/example/models/ArticlePage.php**

```php
#[
    Label([
        'en' => 'Introduction',
        'de' => 'Einleitung',
    ]),
    Type(FieldTypes::TEXT),
]
public Field $introduction;

```

## Benefits of using this plugin

You could alternatively use another plugin by @lukaskleinschmidt to [create type-hints](https://github.com/lukaskleinschmidt/kirby-file-types) based on your regular Kirby setup but that would mean you need to update them on every code change. With my plugin you can define your fields in the PageModel and instantly have code-completion in your templates. Hovering the property name will, in most IDEs, show you the attributes you did set for easy reference.

You could reduce the risk of typos and get auto-completion if you use my [Schema for Kirby’s YAML Blueprints](https://github.com/bnomei/kirby3-schema). But using the `*::make()`-helpers and the PHP attributes will get you code-completion and type-safety within the blueprints themselves and in the rest of your PHP code (the PageModels, controllers, templates, …).

Looking forward to your feedback,

- Bruno

---

<div class="post-metadata">

**Author:** ![fvsch](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/fvsch/32/15908_2.png) [@fvsch](https://forum.getkirby.com/u/fvsch)\
**Post date:** [November 25, 2023, 12:16pm UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/2 "2023-11-25T12:16:06Z")

</div>

Love the concept, have to try it soon to be able to give more feedback.

I’m wondering, if you have page model attributes for fields, could a basic blueprint be generated automatically from those?

---

<div class="post-metadata">

**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\
**Post date:** [November 25, 2023, 7:13pm UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/3 "2023-11-25T19:13:28Z")

</div>

using the `HasBlueprintFromAttributes` should be enough to generate a fields-only blueprint.  
you still need to register that blueprint array either with the autoloader plugin or manually. see [https://github.com/bnomei/kirby-blueprints/blob/main/classes/Blueprints/HasBlueprintFromAttributes.php](https://github.com/bnomei/kirby-blueprints/blob/main/classes/Blueprints/HasBlueprintFromAttributes.php)

see this example

> <https://github.com/bnomei/kirby-blueprints/blob/main/tests/site/plugins/test/models/HomePage.php>

---

<div class="post-metadata">

**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\
**Post date:** [November 26, 2023, 5:39pm UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/4 "2023-11-26T17:39:49Z")

</div>

The most recent version adds the `Ink` helpers. They wrap around the many static `*::make` methods while keeping static analysis happy.

**The biggest advantage of `Ink` is that your IDEs highlighting will make your blueprints more readable than ever.**

 ![pagemodel](https://europe1.discourse-cdn.com/flex017/uploads/getkirby/original/2X/4/41b1a2fc6d77e516d2d7c919fc6d65b15c62a934.png)  
 ![panel](https://europe1.discourse-cdn.com/flex017/uploads/getkirby/original/2X/d/d157939a62bee1c0e72219faa402244f29e1f8ec.png)

---

<div class="post-metadata">

**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\
**Post date:** [November 26, 2023, 6:32pm UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/5 "2023-11-26T18:32:08Z")

</div>

Why should you care about PHP based blueprints? As the excellent cookbook by @texnixe points out you **can react dynamically on the state of your kirby installation**.

> **[Programmable blueprints](https://getkirby.com/docs/cookbook/panel/programmable-blueprints)**
>
> Create blueprints programmatically with PHP

many popular plugins use the same technique to show fields or sections depending on context of your page. like @tobimori 's seo plugin

> <https://github.com/tobimori/kirby-seo/tree/main/blueprints/fields>
>
> //github.com/tobimori/kirby-seo/tree/main/blueprints/fields

my favorite use case is showing/hiding fields depending on the role of the user which complements the [bouncer plugin](https://github.com/sylvainjule/kirby-bouncer), default `when`-conditionals or [when-query](https://github.com/rasteiner/k3-whenquery) plugin nicely.

```php
    #[
        Blueprint
    ]
    public static function showAdminToolsBlueprint(): array
    {
        $role = kirby()->user()?->role();
        $isAdmin = $role == 'admin'; // use == or cast to string
        $adminTools = Ink::fields()
            ->fields([
                Ink::field(Ink::HEADLINE)
                    ->label('Admin Tools ('.$role.')'),
                Ink::field(Ink::SELECT)
                    ->label('State')
                    ->property('options', [
                        'new' => 'New',
                        'approved' => 'Approved',
                        'rejected' => 'Rejected',
                    ])
            ]);

        return Ink::page(
            title: 'Project',
            columns: [
                Ink::column(2 / 3)->fields([
                    //..
                ]),
                Ink::column(1 / 3)->sections([
                    Ink::files(label: 'Files'),
                    $isAdmin ? $adminTools : null,
                ]),
            ],
        )->toArray();
}

```

---

<div class="post-metadata">

**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\
**Post date:** [November 26, 2023, 7:11pm UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/6 "2023-11-26T19:11:32Z")

</div>

If you do not like typing out the many functions or want to be closer to yaml visually you can use the named properties syntax as well.

```php
Ink::column(
    width: 2 / 3,
    fields: [
        'leftEar',
        Ink::field(
            type: Ink::BLOCKS,
            label: 'Trunk',
            properties: [
                Ink::EMPTY => '🐘'
            ]
        ),
        'rightEar',
    ]
),

```

---

<div class="post-metadata">

**Author:** ![bnomei](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/bnomei/32/775_2.png) [@bnomei](https://forum.getkirby.com/u/bnomei)\
**Post date:** [July 24, 2024, 7:16am UTC](https://forum.getkirby.com/t/kirby-ink-php-class-based-blueprints/30088/7 "2024-07-24T07:16:07Z")

</div>

The [code coverage for Ink’s core logic](https://codeclimate.com/github/bnomei/kirby-blueprints) has been improved to 91%.

Thanks to @tobimori for his feedback on Ink.

Have fun writing fast and dynamic blueprints in PHP!