Creating a Baun Plugin

Once you understand the basics of the Baun plugin architecture you can get started creating your own plugins. A basic plugin folder structure should look like this:

/myplugin
    /src
        - MyClass.php
    - composer.json

composer.json

The composer.json file is not only required to distribute your plugin (via Packagist) but it also sets up class autoloading which is required for Baun plugins to work. A basic composer.json should look like this:

{
    "name": "gilbitron/myplugin",
    "description": "A Baun plugin that does something cool",
    "license": "MIT",
    "authors": [
        {
            "name": "Gilbert Pellegrom",
            "email": "gilbert@pellegrom.me"
        }
    ],
    "require": {},
    "autoload": {
        "psr-4": {
            "Gilbitron\\Myplugin\\": "src/"
        }
    }
}

The important things to notice here are:

  • name - This is the name of your package and the string that users need to add to their composer.json to install your plugin.
  • autoload - This tells composer to autoload everything in the /src folder using the namespace Gilbitron\Myplugin. More on that below.

Autoloading

Each plugin must have an autoloaded class that is used to load the plugin in Baun. Baun uses PSR-4 autoloading which means the classes are autoloaded using a namespace. The namespace and class name are what the user must add in config/plugins.php. For example:

return [

    'Gilbitron\Myplugin\MyClass',

];

In this example Gilbitron\Myplugin is the namespace defined in composer.json and MyClass is the name of the class. The class can then use namespaces to autoload other classes you want to include as normal.

Plugin Class

Now that your plugin class is loaded by Baun you can start writing some code. Your Baun plugin should extend the Baun\Plugin class as it handles the setup of the plugin. A basic plugin class might look like:

<?php namespace Gilbitron\Myplugin;

use Baun\Plugin;

class MyClass extends Plugin {

    public function init()
    {
        $this->events->addListener('baun.loaded', [$this, 'sayHello']);
    }

    public function sayHello()
    {
        echo 'Hello World!';
    }

}

Note that we don't use a constructor but instead we use an init() function. This is simply to keep things clean.

You will also notice the use of $this->events in the code above. Baun abstracts out much of its implementation into Providers to make it easy to create your own custom providers and change them as required. The config and providers available from Baun\Plugin are as follows:

Provider Description
$this->config Access to config data (e.g. $this->config->get('app.debug'))
$this->events Events provider (see the events docs)
$this->router Router provider
$this->theme Theme provider
$this->contentParser Content parser provider

To get an idea of how to use these providers have a look at the Blog RSS plugin source code.

Config & Assets

If your plugin requires custom config files or custom assets you should include these in the /config and /assets folders of your plugin respectively. After a user has installed your plugin they will then need to use the Baun CLI to publish these files (copy them) into the Baun install. This can be done using the following commands:

php baun publish:config gilbitron/myplugin
php baun publish:assets gilbitron/myplugin

Where gilbitron/myplugin is the name of your plugin in composer.json. Once published the files can be found in the following locations:

  • Config files will be published to the config/plugins/gilbitron/myplugin folder
  • Assets will be published to the public/assets/plugins/gilbitron/myplugin folder