Extending
Herbie can be extended at several points in the application lifecycle. You can add functionality in different ways, from simple PHP files in the filesystem to distributed Composer plugins.
Extension points
| Extension point | Typical use | Difficulty | Frequency |
|---|---|---|---|
| Console command | Provide functionality in the CLI | Medium | Rare |
| Event listener | React to system events | Medium | Rare |
| Application middleware | Modify HTTP requests and responses | Medium | Rare |
| Route middleware | Modify HTTP requests and responses for matching routes | Medium | Rare |
| Twig filter | Transform values in templates | Very easy | Frequent |
| Twig global | Provide a global value or helper object | Very easy | Frequent |
| Twig function | Generate content in templates | Very easy | Frequent |
| Twig test | Evaluate boolean conditions in templates | Very easy | Frequent |
For details on specific extension points, see Commands, Event Listeners, Middlewares, Twig Filters, Twig Functions, Twig Globals, and Twig Tests.
Extension methods
There are four ways to add extensions, with increasing flexibility and complexity.
| Method | Difficulty | Reusability |
|---|---|---|
| Using the filesystem | Very easy | Low |
| Using a programmatic approach | Easy | Low |
| Using a plugin | Medium | Medium |
| Using a distributed plugin | High | High |
Choosing a method
- Filesystem: Best for small, project-specific extensions that should be quick to add.
- Programmatic: Useful when extensions should be registered explicitly in
index.php, for example together with custom bootstrap logic. - Plugin: Suitable for grouping related extensions in one class, with optional configuration and dependency checks.
- Distributed plugin: Use this when an extension should be versioned, shared, and installed via Composer.
Extending using the filesystem
With the filesystem approach, you add extensions by placing PHP files in the corresponding directories inside site/extend.
| Directory | Description |
|---|---|
| site/extend | The directory with various customized extensions. |
| site/extend/commands | Directory with customized console commands. |
| site/extend/events | Directory with customized event listeners. |
| site/extend/middlewares_app | Directory with customized application middlewares. |
| site/extend/middlewares_route | Directory with customized route middlewares. |
| site/extend/twig_filters | Directory with customized Twig Filters. |
| site/extend/twig_functions | Directory with customized Twig Functions. |
| site/extend/twig_globals | Directory with customized Twig Globals. |
| site/extend/twig_tests | Directory with customized Twig Tests. |
Each file must return the value expected by the extension point. Herbie discovers and registers these files automatically.
| Extension point | Return value |
|---|---|
| Console command | Command class string |
| Event listener | [eventName, callable] or [eventName, callable, priority] |
| Application middleware | Middleware (callable, instance, or class string) |
| Route middleware | [routeRegex, middleware] |
| Twig filter | [name, callable] or [name, callable, options] |
| Twig function | [name, callable] or [name, callable, options] |
| Twig global | [name, value] |
| Twig test | [name, callable] or [name, callable, options] |
Console commands
To add a console command, create a PHP file in site/extend/commands that returns a command class.
The command is registered automatically and becomes available in the CLI.
<?php
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
class CustomCommand extends Command
{
protected static $defaultName = 'custom';
protected static $defaultDescription = 'A custom command.';
protected function configure(): void
{
$this->setHelp('This is a custom command.');
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$output->writeln('Message from custom command.');
return Command::SUCCESS;
}
}
return CustomCommand::class;
Event listeners
To add an event listener, create a PHP file in site/extend/events that returns an array with the event class name and a callable.
The listener is registered automatically.
<?php
use herbie\events\TwigInitializedEvent;
$event = function (TwigInitializedEvent $event): void {
// do something with $event
};
return [TwigInitializedEvent::class, $event];
Application middlewares
To add an application middleware, create a PHP file in site/extend/middlewares_app that returns a middleware.
The middleware is registered automatically.
<?php
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
$middleware = function (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
// do something with the request
$response = $handler->handle($request);
// do something with the response
return $response;
};
return $middleware;
Route middlewares
To add a route middleware, create a PHP file in site/extend/middlewares_route that returns an array with a route regular expression and a middleware.
The middleware is registered automatically.
<?php
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
$middleware = function (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
// do something with the request
$response = $handler->handle($request);
// do something with the response
return $response;
};
return ['^route/.*', $middleware];
Twig filters
To add a Twig filter, create a PHP file in site/extend/twig_filters that returns an array with the filter name and a callable.
The filter is registered automatically.
<?php
$twigFilter = function (string $string): string {
return strrev($string);
};
return ['reverse', $twigFilter];
Twig functions
To add a Twig function, create a PHP file in site/extend/twig_functions that returns an array with the function name and a callable.
The function is registered automatically.
<?php
$twigFunction = function (string $name): string {
return "Hello {$name}!";
};
return ['hello', $twigFunction];
Twig globals
To add a Twig global, create a PHP file in site/extend/twig_globals that returns an array with the global name and its value.
The global is registered automatically.
<?php
return ['hello', 'world'];
Twig tests
To add a Twig test, create a PHP file in site/extend/twig_tests that returns an array with the test name and a callable.
The test is registered automatically.
<?php
$twigTest = function (int $value): bool {
return ($value % 2) !== 0;
};
return ['odd', $twigTest];
Extending using a programmatic approach
With the programmatic approach, you register extensions in the index.php bootstrap file.
The herbie\Application class provides add* methods for this purpose.
A simplified bootstrap file looks like this:
<?php
use herbie\Application;
use herbie\ApplicationPaths;
use herbie\events\TwigInitializedEvent;
$app = new Application(
new ApplicationPaths(__DIR__)
);
// Register extensions here, for example:
// $app->addConsoleCommand(CustomCommand::class);
// $app->addEventListener(TwigInitializedEvent::class, $event);
// $app->addApplicationMiddleware($middleware);
// $app->addRouteMiddleware('^route/.*', $middleware);
// $app->addTwigFilter('reverse', $twigFilter);
// $app->addTwigFunction('hello', $twigFunction);
// $app->addTwigGlobal('datetime', $twigGlobal);
// $app->addTwigTest('odd', $twigTest);
$app->run();
The following examples show how to register each extension point.
Console command
class CustomCommand extends Command
{
// see class definition above
}
$app->addConsoleCommand(CustomCommand::class);
Event listener
use herbie\events\TwigInitializedEvent;
$event = function (TwigInitializedEvent $event): void {
// do something with $event
};
$app->addEventListener(TwigInitializedEvent::class, $event);
Application middleware
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
$middleware = function (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
// do something with the request
$response = $handler->handle($request);
// do something with the response
return $response;
};
$app->addApplicationMiddleware($middleware);
Route middleware
// the route middleware can be the same as the application middleware
$app->addRouteMiddleware('^route/.*', $middleware);
Twig filter
$twigFilter = function (string $string): string {
return strrev($string);
};
$app->addTwigFilter('reverse', $twigFilter);
Twig global
$twigGlobal = new My\Custom\DateTime();
$app->addTwigGlobal('datetime', $twigGlobal);
Twig function
$twigFunction = function (string $name): string {
return "Hello {$name}!";
};
$app->addTwigFunction('hello', $twigFunction);
Twig test
$twigTest = function (int $value): bool {
return ($value % 2) !== 0;
};
$app->addTwigTest('odd', $twigTest);
Extending using a plugin
A plugin bundles extensions in a dedicated class. This approach is more flexible than the filesystem and programmatic approaches:
- it keeps related extensions together in one place
- it can provide configuration and declare dependencies
- it has access to application services through dependency injection
A plugin is a directory with a PHP class that is marked with the #[Plugin] attribute.
myplugin
└── MyPlugin.php
The first argument of the attribute is the name of the plugin, which is used in the enabledPlugins setting and as key plugins.myplugin in the configuration.
Herbie finds the class by scanning the PHP files in the plugin directory, one level deep, without executing them.
There is one plugin per directory.
The result of the search is cached in site/runtime/cache/system/plugins.php, but not in debug mode (environment variable HERBIE_DEBUG).
The cache is renewed if a plugin directory or a Composer plugin is added, removed or updated.
If you change an existing plugin file in a production environment, clear the cache with the command clear-files.
A plugin can have default values for its settings.
They are returned by an optional file config.php in the plugin directory and can be overridden in the configuration file site/config/main.php.
myplugin
├── config.php
└── MyPlugin.php
The config file must look like this:
<?php
return [
'greeting' => 'Hello',
];
A plugin can declare the Composer packages it needs with the argument requires of the attribute, a list of packages with a version constraint.
The packages are checked when the plugin is enabled, packages of plugins that are not enabled are not checked.
If a package is missing or does not match the version constraint, Herbie throws an exception that tells what to install.
#[Plugin('myplugin', requires: ['league/commonmark' => '^2.10'])]
class MyPlugin implements herbie\PluginInterface
The plugin itself is a PHP class with the following methods:
<?php
use herbie\Plugin;
#[Plugin('myplugin')]
class MyPlugin implements herbie\PluginInterface
{
public function apiVersion(): int
{
return 2;
}
public function consoleCommands(): array
{
return [];
}
public function eventListeners(): array
{
return [];
}
public function applicationMiddlewares(): array
{
return [];
}
public function routeMiddlewares(): array
{
return [];
}
public function twigFilters(): array
{
return [];
}
public function twigGlobals(): array
{
return [];
}
public function twigFunctions(): array
{
return [];
}
public function twigTests(): array
{
return [];
}
}
To install the plugin, place its directory in site/extend/plugins.
To enable the plugin, add it to the comma-separated enabledPlugins setting in site/config/main.php.
<?php
return [
'enabledPlugins' => 'markdown,myplugin,textile',
];
A complete plugin class can look like this:
<?php
use herbie\Plugin;
use herbie\events\TwigInitializedEvent;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
class CustomCommand extends Command
{
protected static $defaultName = 'custom';
protected static $defaultDescription = 'A custom command.';
protected function configure(): void
{
$this->setHelp('This is a custom command.');
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$output->writeln('Message from custom command.');
return Command::SUCCESS;
}
}
#[Plugin('myplugin')]
class MyPlugin implements herbie\PluginInterface
{
public function apiVersion(): int
{
return 2;
}
public function consoleCommands(): array
{
return [
CustomCommand::class
];
}
public function eventListeners(): array
{
$event = function (TwigInitializedEvent $event): void {
// do something with $event
};
return [
[TwigInitializedEvent::class, $event]
];
}
public function applicationMiddlewares(): array
{
$middleware = function (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
// do something with the request
$response = $handler->handle($request);
// do something with the response
return $response;
};
return [
$middleware
];
}
public function routeMiddlewares(): array
{
$middleware = function (ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
// do something with the request
$response = $handler->handle($request);
// do something with the response
return $response;
};
return [
['^route/.*', $middleware]
];
}
public function twigFilters(): array
{
$twigFilter = function (string $string): string {
return strrev($string);
};
return [
['reverse', $twigFilter]
];
}
public function twigGlobals(): array
{
return [
['hello', 'world']
];
}
public function twigFunctions(): array
{
$twigFunction = function (string $name): string {
return "Hello {$name}!";
};
return [
['hello', $twigFunction]
];
}
public function twigTests(): array
{
$twigTest = function (int $value): bool {
return ($value % 2) !== 0;
};
return [
['odd', $twigTest]
];
}
}
For a complete example, see the dummy system plugin.
Extending using a distributed plugin
To distribute a plugin, turn it into a Composer package.
Create a composer.json file in the plugin directory and set its type to herbie-plugin.
{
"name": "myvendor/myplugin",
"type": "herbie-plugin",
"require-dev": {
"getherbie/herbie": "dev-3.x"
}
}
See the Composer documentation for details on publishing packages to Packagist.
After publishing, install the plugin in your project with Composer:
composer require myvendor/myplugin
Then enable the plugin in the configuration.
The contact and search plugins, which ship with Herbie, are good examples of distributed plugins.