Extending / Basics / Creating a New Extension
Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?
Creating a Bolt Extension or Theme¶
Extensions and themes that are published on the Marketplace must follow a few simple rules to allow them to hook into a Bolt installation. Information about the package needs to be provided in JSON format in the root of a project.
To be hosted on the Bolt Marketplace your project will need to be stored in a VCS repository and publicly readable. If you want to install your own extensions from somewhere other than the official Bolt marketplace then see the advanced documentation page.
PHP namespace¶
Extensions should use the PHP namespace of
Bolt\Extension\{author name}\{extension name}\
e.g.
Bolt\Extension\MyName\MyExtension\
.
Using the Starter Package¶
To make getting setup with an extension as simple as possible there is a skeleton extension package that can get you started.
The fastest way to build an extension is on your local workstation with an install of Bolt, and create your new extension's git repository.
For this example, we'll assume that your new extension's git repository is
located at /home/user/development/myextension/
, and the name of the
extension in its composer.json
file is myname/myextension
.
cd /home/user/development/
composer create-project --no-install bolt/bolt-extension-starter:^3.0 myextension
cd myextension
git init
git add .
git commit . -m "First commit of my new extension"
Once you've run the above commands, Composer will create a new directory with
the bare extension. You should then open the project in your editor and you will
need to make a few changes, giving your new extension the correct configuration
and namespaces. There are two files you need to edit immediately, composer.json
,
and src/ExtensionNameExtension.php
.
- Change the namespace at the top of
src/ExtensionNameExtension.php
to your own. - Rename the class
ExtensionNameExtension
to match the name of your extension plus the "Extension" suffix, e.g.KoalaCatcherExtension
- Rename the file
src/ExtensionNameExtension.php
to match your extension's name plus the "Extension" suffix, e.g.src/KoalaCatcherExtension.php
- In
composer.json
change the name setting to your extension name eg:myvendorname/extensionname
. For clarity, this should match the folder names you created earlier - In
composer.json
give a description and a type, eitherbolt-extension
orbolt-theme
- In
composer.json
add your contact information to the author section - In the
autoload
section ofcomposer.json
update the PSR-4 namespace to the one you have used in your extension files - In the
extra
section ofcomposer.json
updatebolt-class
to reflect the new namespace and class name (from steps 1 & 2).
The above steps will get you started, and below is some more in depth information about the configuration.
Installing the new extension¶
In order to make the extension installable via Composer, you will first need to
define the location of the extension's git repository at the top of the
"repositories"
section of your local Bolt site's extensions/composer.json
file, e.g.
"repositories": {
"myextension-git-repo": {
"type": "path",
"url": "/home/user/development/myextension/",
"options": {
"symlink": false
}
},
"packagist": false,
"bolt": {
"type": "composer",
"url": "https://market.bolt.cm/satis/"
}
},
Note that the most important part above is the value give to the "url":
key,
this value is the path to your extension's local git repository, and can be
either the full path (recommended) or a path relative to the location of the
extensions/
directory.
Note: Placing the "myextension-git-repo"
section at the top will give it priority over a matching package name on the
Bolt Marketplace.
Next you will need to update the "minimum-stability"
value in your local Bolt
site's extensions/composer.json
file, e.g.
"minimum-stability": "dev",
Note: This setting should also be changed in
your app/config/config.yml
file as it will be overwritten the next
time you load the Extensions page in the Bolt back-end.
This will allow you to install the current development version of your new extension.
As the extension is in a local git repository, the version may be inferred by
the branch or tag that is currently checked out. Otherwise, the version should
be explicitly defined in the extension's composer.json
file, e.g.
"version": "x.y.z",
If Composer cannot resolved the version by these means, it will assumed the
version to be dev-master
.
Finally you can add your extension to the "require"
section on your local
Bolt site's extensions/composer.json
file, e.g.
"require": {
"myname/myextension": "dev-master@dev"
},
}
Once this is done, you can now either run composer update
inside the
extensions/
directory of your local Bolt site, or by pressing the
"Run all Updates" button on the Extensions page in the Bolt back-end.
Extended starter extension¶
When you want a starter extension with more example code, create a new one from this repository instead of the above one.
composer create-project --no-install bolt/bolt-extension-starter-extended:^3.0 <newextname>
Publishing Your Extension on the Marketplace¶
Once you have the above file setup, make sure it is pushed up to your hosted repository then visit market.bolt.cm to register your extension or theme on the Bolt Marketplace.
For any screenshots of your extension or theme along with icons see Market Place Visual Assets Best Practices
See the testing and debugging instructions for further information about tagging and automated testing of your extension.
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.