Download the PHP package bnomei/kirby-blueprints without Composer

Kirby Blueprints

Kirby Ink - PHP Class-based Blueprints for Kirby CMS for better type safety and code completion.

Install

Using composer:

Commercial Usage

Support open source!

This plugin is free but if you use it in a commercial project please consider to sponsor me or make a donation.
If my work helped you to make some cash it seems fair to me that I might get a little reward as well, right?

Be kind. Share a little. Thanks.

‐ Bruno
 

What's in the box?

This plugin introduces two new ways to define blueprints for Kirby.

Blueprint definitions from Files

How to make Kirby aware of a blueprint definition

Kirby can currently only load blueprints from YAML files if they are stored in the site/blueprints folder. It can also load them from PHP files but they need to be defined in a custom plugin with something called extension. Give my suggestion an up-vote if you want to see this changed in the future and be able to use PHP blueprints right from the core folders.

The examples in this Readme show how to create various blueprints. What is not show here is how to register them in the index.php of your custom plugin via an extension. See the official docs on how to do that or try my autoloader helper.

The following code shows how you would use the autoloader helper in your custom plugin. As it's name indicates the helper will automatically scan the folders inside your plugin and register ALL extensions it finds (like blueprints, pageModels, snippets, ... and many more). Meaning that it will also register the blueprints from the site/plugins/example/blueprints folder.

site/plugins/example/index.php

Creating blueprints with YAML in a custom plugin (core Kirby feature)

This is the way you are currently using to define a blueprint in Kirby via a plugin extension.

site/plugins/example/blueprints/fields/description.yml

Creating blueprints with PHP in a custom plugin

In addition to the core array-definition his plugin introduces two new ways to define blueprints. The fluent- and the named parameter-definition. In the end they are both converted to the same array-definition that Kirby expects but you can use the *::make()-helpers to create them and avoid typos.

Programmable Blueprints in Kirby array-definition (core feature)

You can use a PHP file to define a blueprint if you registered it in the index.php of your plugin or used the autoloader helper.

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

Fluent Definition

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

Named Parameter Definition

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

Dynamic Blueprints without PHP Attributes on Models

If you want to return a dynamic definition for a blueprint you need to wrap the return value of your PHP-based blueprint in a callback. This is because otherwise the blueprint definitions get parsed during Kirby's initial setup and you can NOT access all data in the Kirby instance (kirby()) or any other helpers (site()/page()) without causing issues. But using the closure will delay the parsing of the blueprint until the blueprint is actually needed after Kirby has loaded all plugins and is ready to render a page.

site/plugins/example/blueprints/fields/version.php

NOTE: For Models you can do that with the defer option. See further down.

Available Make-Helpers

Depending on what blueprint you want to create you can use one of the following helpers.

• Field::make()
• Section::make()
• Column::make()
• Tab::make()
• Page::make()
• File::make()
• User::make()
• Site::make()

Dynamic Blueprints

Since the blueprint definitions get parsed during Kirby's initial setup you can NOT access all data in the Kirby instance (kirby()) or any other helpers (site()/page()) without causing issues once in a while. If you need dynamic behaviour in your blueprints consider reading up on the system.loadPlugins:after hook.

Also take a look at the official cookbook and the examples in this plugin related to dynamic blueprints.

Blueprint definitions from PageModels (new feature from plugin)

In Kirby you can define a class matching the name of your template plus the suffix Page to create a PageModel. In this example we are putting them into the site/plugins/example/models folder so that the autoloader helper can find them. You could also put them into the site/models folder given you adjust the filename a bit.

site/plugins/example/models/ExamplePage.php

Creating field definitions with PHP Attributes in a PageModel

Do not be confused by the many use statements you will see in the examples below. Your IDE will most likely add them when you use the PHP attributes to ensure the PHP code knows where to find the definitions for them.

You will need to add two traits to your PageModel.

• One for making it aware that we want the public properties with attributes registered as blueprint fields and to read the page blueprint definition (HasBlueprintFromAttributes) and
• a second one for making those public properties return the Kirby field object (HasPublicPropertiesMappedToKirbyFields).

Without defining a YAML blueprint for the article template Kirby would have an empty blueprint definition. But with the attributes defined in the PageModel Kirby will know what fields we want to have in the blueprint (registered by the autoloader helper).

site/plugins/example/models/ArticlePage.php

Just to be extra clear: This would be the same as having the following YAML blueprint definition. Only that we do not need to actually create it because the attributes in the PageModel will be doing that for us.

site/plugins/example/blueprints/pages/article.yml

Most likely you will want a more complex blueprint definition than just fields at root level. To do that you will have to create a method to return the blueprint from the PageModel. The name of the method does not matter but the attribute Blueprint does. The method needs to return an array with the blueprint definition. See futher down for an example.

Available Attributes

You can find all available PHP attributes in the classes/Blueprints/Attributes folder of this repository. They reflect the properties you would set for a given field in a YAML blueprint. For some properties I created variants since different fields use the same property name but with different meanings (like max in a number field vs. max in a date field) and I wanted to keep them unambiguous in PHP.

Alpha, Accept, After, Api, Autocomplete, Autofocus, Before, Blueprint, Buttons, Calendar, Columns, ColumnsCount, Converter, Counter, CustomType, DefaultValue, Disabled, Display, EmptyValue, ExtendsField, Fieldsets, Fields, Files, Font, Format, GenericAttribute, Grow, Help, Icon, Image, Info, Inline, Label, Layout, LayoutSettings, Layouts, Link, Marks, Max, MaxDate, MaxRange, MaxTime, MaxLength, Min, MinDate, MinLength, MinRange, MinTime, Mode, Multiple, Nodes, Numbered, Options, Path, Pattern, Placeholder, Prepend, Property, Query, Range, Required, Reset, Search, Separator, Size, SortBy, Sortable, Spellcheck, Step, Store, Subpages, Sync, Text, Theme, Time, TimeNotation, Tooltip, Translate, Type, Uploads, When, Width, Wizard

Benefits of using this plugin

You could alternatively use another plugin to create type-hints based on your regular Kirby setup but that would mean you need to update them on every code change. With this 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. 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, ...).

site/templates/article.php

NOTE: This in not perfect. In an ideal case the IDE would know that you wanted a field of type textarea and only offer you methods that are available for that type of field. But that is something we can not do with Kirby right now. Still it's better than nothing. :-)

How to re-use blueprint definitions

There are two ways to re-use blueprint definitions.

• One is to mimic the extends keyword from the YAML blueprints but use it as the ExtendsField attribute in PHP PageModels. You can extend from both YAML and PHP blueprints.
• The other would be to create a PHP trait with the field definition you want to re-use and apply the trait to multiple classes.

Re-use by extending from YAML/PHP-based blueprints

site/plugins/example/blueprints/fields/special-date.yml

site/plugins/example/models/MemberPage.php

Using Traits to re-use blueprints

site/plugins/example/classes/HasDescription.php

site/plugins/example/models/BlogpostPage.php

Blueprint definitions for a page from a PageModel

You will use the *::make()-helpers to create a blueprint definition in a PHP blueprint files. If you want your attribute based fields from the PageModel to work you need to directly define a full page blueprint in the same PageModel. Why is it needed? Because the attribute based fields need to be injected in the blueprint definition and that can only work if you define the blueprint in the PageModel itself.

This will also give you the benefit of not having any blueprint files at all.

site/plugins/example/models/ArticlePage.php

There is one special behaviour to note here. You can make the blueprint expand the fields defined by attributes in referencing them by name and setting their value to true. But this will only work in blueprints defined in PageModels not for those from PHP blueprint files.

Why is it called Ink?

Because on top of all these *::make()-helpers it also introduces a new Ink::*-helpers to create a blueprint definition from a PageModel. And because it's short and easy to remember.

Caching and Lazy-loading of PHP based blueprints

If caching is enabled it will only compile the blueprint once and then use the cached version. The cache lasts for the duration set.

The default can be set in the config.php of your plugin with the bnomei.blueprints.expire option.

If defer is set to true it will compile the blueprint after the kirby instance is ready. This means you can use the kirby()/site()/page()-helpers in your blueprints or query the content of the site. Most of the time it makes sense to disable caching when using defer since the cache might interfere with the dynamic behaviour you are trying to create.

Caching for PHP and YAML based blueprints

If you are not using the attributes to define your blueprint definitions you can still enable caching using traits model. One to enable the cache and one to define if it should resolve all fields as much as possible.

Resolving the fields means to write all meta-data in extracting them using a model instance. So if you are using the Kirby query-strings language or other dynamic values in your blueprints (like the Janitor or some SEO plugins do), you might want to skip resolving. But... if you have a very complex blueprint with many fields and you want to speed up the blueprint loading you might want to resolve them. Especially when using lots of Layouts, Columns & Blocks resolving might be a good idea.

site/models/example.php

The cache will use the duration as defined in the bnomei.blueprints.expire option in the config.php of your plugin.

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

MIT

It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.