Guides
Package a feature as an extension
Ship a Composer package that appears in Extensions, turns on with one action, and adds its own blocks and permissions.
At the end of this page you have a Composer package that adds a feature to Thallo: it appears in Extensions › Capabilities as soon as it is installed, turns on with the same one action as Commerce, adds its own block type in every workspace, and grants its own permission to the superuser and administrator roles. Turning it off hides it and keeps its data.
You need a PHP package you can composer require into a Thallo project, and a working
knowledge of Glueful extensions: a provider class and migrations. The example is a booking
feature, acme/bookings.
How Thallo sees your package
Your package is a Glueful extension: Composer type glueful-extension, with a provider class
and migrations in extra.glueful. On top of that it declares a capability, the switch an
operator sees, in extra.thallo.capabilities. Thallo reads the declaration from Composer's
metadata, so the capability is listed while your extension is still disabled.
Each capability is managed in one of three ways, its mode:
| Mode | What the operator gets |
|---|---|
simple |
A plain switch on the capability's card. The default when you leave mode out. |
activation |
One action that enables and migrates your extension, checks it in a fresh request, adds its blocks, grants its permissions, then switches the capability on. Your extension is managed by the capability: the generic Enable and Disable refuse it. |
external_flow |
A link to a page of yours that runs its own flow, named by destination. |
Use activation when your feature has an extension of its own to enable. The rest of this page
builds one.
Declare the capability
composer.json in your package:
{
"name": "acme/bookings",
"type": "glueful-extension",
"autoload": {
"psr-4": { "Acme\\Bookings\\": "src/" },
"classmap": ["migrations/"]
},
"extra": {
"glueful": {
"provider": "Acme\\Bookings\\BookingsServiceProvider",
"requires": { "glueful": ">=1.79.0", "extensions": [] },
"migrations": [
{ "id": "default", "path": "migrations", "priority": "dependent", "mode": "on_enable" }
]
},
"thallo": {
"capabilities": [
{
"id": "acme.bookings",
"label": "Bookings",
"description": "Appointments your visitors book from your pages.",
"mode": "activation",
"copy": {
"turn_on": "This prepares Bookings and adds its block. Your existing content is kept.",
"turn_off": "The Bookings block is hidden. Your bookings are kept, and you can turn it on again.",
"links": [{ "label": "Block types", "to": "/settings/block-types" }]
}
}
]
}
}
} The keys of a capability:
| Key | Required | What it does |
|---|---|---|
id |
yes | The capability's id. Use your vendor as the prefix; thallo. belongs to Thallo. |
label, description |
no | What the card shows. |
mode |
no | simple, activation or external_flow. |
requires |
no | Ids of capabilities this one needs on. |
copy |
no | turn_on and turn_off, the text of the confirmation dialogs, and links, each a label and an admin path to, shown on the card once it is on. Generic wording fills in what you leave out. |
destination |
for external_flow |
path and label of the page that runs your flow. |
The capability belongs to the package that declares it: an activation capability's engine is
always your own package. Migrations with "mode": "on_enable" run when the activation enables
your extension, not when Composer installs it.
A provider can declare capabilities in code instead, by implementing
Thallo\Contracts\Capability\DeclaresCapabilities, whose capabilities() returns a list of
Thallo\Contracts\Capability\Capability. Thallo's own packs do this. Composer metadata is the
better choice for an extension, because it is read while the extension is disabled.
Add a block type
Contribute block types through Thallo\Contracts\Starter\StarterBlockTypeContributor, and set
requiresCapability to your capability's id. The activation seeds them, in every workspace when
workspaces are on, and Thallo hides them while the capability is off, without deleting them:
<?php
namespace Acme\Bookings;
use Thallo\Contracts\Starter\StarterBlockTypeContributor;
use Thallo\Contracts\Starter\StarterBlockTypeDefinition;
final class BookingBlockTypes implements StarterBlockTypeContributor
{
public function blockTypeDefinitions(): array
{
return [
new StarterBlockTypeDefinition(
sourceId: 'acme-bookings:booking-form',
slug: 'booking_form',
label: 'Booking form',
icon: 'i-lucide-calendar-check',
category: 'forms',
description: 'Lets visitors book an appointment.',
schema: [['name' => 'heading', 'type' => 'string']],
requiresCapability: 'acme.bookings',
),
];
}
} When a later release changes the definition, thallo:provision brings existing installs up to
date. By default it only adds: a new field is appended, and a field you dropped, or choices you
changed, stay as they were stored. Set ownsSchema: true when your definition owns the block's
fields. Provision then replaces the stored fields with yours, so a dropped field goes and changed
choices apply. A field someone added to the block in the admin goes too.
Register it, and declare a permission
Your provider registers the contributor with Thallo\Contracts\Starter\StarterBlockTypeRegistry
when it boots (once: boot can run more than once in a process), and declares its permissions in
permissions(). The activation grants them to the superuser and administrator roles; a
permission an operator revokes later stays revoked. Until your capability's activation runs,
provision syncs your permissions but grants them to no one, even when your extension is already
enabled. That holds for permissions your engine's own provider declares; declare them there.
<?php
namespace Acme\Bookings;
use Glueful\Bootstrap\ApplicationContext;
use Glueful\Extensions\ServiceProvider;
use Glueful\Permissions\Catalog\Permission;
use Thallo\Contracts\Starter\StarterBlockTypeRegistry;
final class BookingsServiceProvider extends ServiceProvider
{
public function boot(ApplicationContext $context): void
{
$container = $context->getContainer();
if (!$container->has(StarterBlockTypeRegistry::class)) {
return;
}
$registry = $container->get(StarterBlockTypeRegistry::class);
foreach ($registry->all() as $contributor) {
if ($contributor instanceof BookingBlockTypes) {
return; // registered already
}
}
$registry->register(new BookingBlockTypes());
}
public function permissions(): array
{
return [
Permission::define('bookings.manage')
->label('Manage bookings')
->category('bookings')
->resource('bookings')
->managedBy('acme/bookings'),
];
}
} Depend on glueful/thallo-contracts only, never on Thallo's other packages: the contracts are the
part of Thallo an extension can rely on.
Check that it is on
Your extension stays enabled while its capability is off, so check the capability before doing
anything a visitor sees. Resolve Thallo\Contracts\Capability\CapabilityRegistry from the
container and ask isEnabled('acme.bookings'). An activation capability reads off until its
activation finishes, even when your extension is already enabled.
Install it and turn it on
composer require acme/bookings Open Extensions › Capabilities. Bookings is listed with its switch, and
Extensions › Installed shows acme/bookings as managed by it. Switch it on, confirm, and the
card ends on what was added, with your links beside it. From a shell:
php glueful thallo:capabilities:enable acme.bookings Turning Bookings off hides the block and keeps your extension enabled, its tables, and its data.
When Thallo refuses a declaration
Thallo blocks a capability, and the packages it claims, when its declaration conflicts or can't be read:
- an entry in
extra.thallo.capabilitiesis invalid (a missing id, an unknown mode), or the value isn't a list; every capability your package declares is blocked with it; - the same id is declared differently by two sources, two packages or a package and Thallo;
- two capabilities that are not
simpleclaim the same package, including one that is blocked for another reason; - an
activationcapability's package is one Thallo requires; - an
activationcapability's package isn't installed.
A blocked capability has no switch, every path refuses it, and php glueful thallo:doctor fails its
capability-declarations check with the reason. See
troubleshooting.
Check it worked
php glueful thallo:capabilities:status acme.bookings is listed as on, and Settings › Block Types shows Booking form. The card in
Extensions › Capabilities says how many blocks were added and permissions granted.