Extending / Basics
Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?
A basic Bolt extension requires the following elements:
- A
composer.json
file to store the extension metadata - A PHP file to operate as the loading/entry point
- An optionaly
config.yml.dist
file that will be copied into the installation'sapp/config/extensions/
directory - A
readme.md
Markdown file to explain to the users of the extension how to configure and use it.
Defining the Namespace¶
The very first thing to note down is the PHP & Composer namespaces your extension will use.
In Bolt, that will be constructed from the following:
- Author name — A name, or nick name, or the person or company authoriing the extension
- Extension name — A descriptive name for your extension
For the purposes of this documentation, we are going to give examples where the
author name is DropBear
and the extension name is KoalaCatcher
.
This would mean the namespaces would become:
Type | Namespace |
---|---|
PHP | Bolt\Extension\DropBear\KoalaCatcher |
Composer | dropbear/koalacatcher |
NOTE: Whenever used inside the composer.json
file, the PHP namepace
should appear with two \\
and not just one, as would be found in a PHP file.
File & Directory Layout¶
Extensions have a required base directory layout, so Bolt & PHP knows where to find certain files.
The base layout looks like:
/
├─ composer.json
├─ readme.md
├─ config
│ └─ config.yml.dist
├─ src
│ └─ KoalaCatcherExtension.php
├─ templates
│ └─ koala.twig
├─ tests
└─ web
└─ dropbear.jpg
└─ koala.js
└─ style.css
File/Directory | Description |
---|---|
composer.json |
All extension metadata: autoloading, author(s), keywords, etc. |
config/ |
Configuration base files (currently only config.yml.dist is supported) |
readme.md |
Markdown file to document use and configuration of the extension. |
src/ |
Extension's PHP code |
templates/ |
Twig templates. These should be kept separate from public assets |
tests/ |
Unit/acceptance test files |
web/ |
Public/web files: CSS, JavaScript, images, etc. |
Extension Loading File¶
All of the extension's PHP files should live in the src/
subdirectory, or
subdirectories under that.
The loading file should be named after the extension, and appended with
Extension.php
. So for our example extension, the file would be
KoalaCatcherExtension.php
.
Bolt will use that name internally to identify your extension, and make it available via the extension service provider.
In its minimalist form, the loading file will contain the following:
namespace Bolt\Extension\DropBear\KoalaCatcher;
use Bolt\Extension\SimpleExtension;
/**
* An extension for catching koalas.
*
* @author Kenny Koala <kenny@dropbear.com.au>
*/
class KoalaCatcherExtension extends SimpleExtension
{
// Extension code goes here.
}
The PHP class Bolt\Extension\SimpleExtension
is an abstract class that
your extension can extend, that will take care of a lot of heavy lifting and code
on your behalf.
Composer's JSON File¶
The final part of a basic extension that needs is the composer.json
file.
Below is an sample file based on our extension's example.
{
"name": "dropbear/koalacatcher",
"description": "Catch koalas",
"type": "bolt-extension",
"keywords": ["koala", "dropbear"],
"require": {
"bolt/bolt": "^3.7"
},
"license": "MIT",
"authors": [
{
"name": "Kenny Koala",
"email": "kenny@dropbear.com.au"
}
],
"autoload": {
"psr-4": {
"Bolt\\Extension\\DropBear\\KoalaCatcher\\": "src"
}
},
"extra": {
"bolt-assets": "web",
"bolt-class": "Bolt\\Extension\\DropBear\\KoalaCatcher\\KoalaCatcherExtension"
}
}
name
— Composer namespace of the extensiondescription
— Brief summary of the extensiontype
— Should be eitherbolt-extension
orbolt-theme
require
— One of the requires must be a version constraint for Bolt, generally"bolt/bolt": "^3.0"
autoload
— Thepsr-4
section must reference the PHP namespace, and have a minimum of"src"
provided as parametersextra
— This section must contain a"bolt-class"
key, with a parameter of the Fully Qualified Class Name (FQCN) of your extension's loader file
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.