Table of Contents
Plugins are a simple way to extend Atomik. As said before, the framework doesn't come with a lot of features. However it provides a nice and powerful plugin system.
Plugins are stored in the app/plugins directory.
Simply copy the plugin file or folder into this directory.
Plugins are not automatically activated. To do so, it's needed to add an entry in the “plugins” configuration key.
Some plugins need custom configuration which can be specified in the plugins config key.
Example 13.2. Plugin with custom configuration
Atomik::set('plugins', array(
'Db' => array(
'dsn' => 'mysql:host=localhost;dbname=atomik',
'username' => 'atomik',
'password' => 'atomik'
),
'Cache'
));
A plugin is made of one file named the same way. For example the Db plugin is in the file
Db.php. Plugin's file should always start with an uppercase letter.
Plugins are loaded at the beginning of a request, just after the configuration. The content of the file is free or it can be a class.
To build more complex plugins you can instead of a file create a folder named after your plugin.
This folder must contain a Plugin.php file.
When using folders, it is possible to add a sub folder named libraries which
will automatically be added to php's include_path.
As said in the "Using plugins" section, plugins can have custom configuration. To retrieve this configuration a $config variable is automatically available. It contains the array used in the configuration.
Example 13.3. Retrieving plugin custom configuration
In the configuration file:
Atomik::set('plugins', array(
'MyPlugin' => array(
'name' => 'Peter'
)
));
In the plugin file:
echo 'hello ' . $config['name'];
For better application design it is advice to use a class to define your plugin. When loading a plugin, it will look for a class named like the plugin suffixed with “Plugin”.
If this class has a static start method, it will be called
with the plugin's custom configuration as argument, when the plugin is loaded.
Example 13.4. Plugin class
The plugin class for a plugin named Db
class DbPlugin
{
public static function start($config)
{
// $config['name'] == 'Peter'
}
}
The class can contain static methods that will be automatically registered as callback on events. These methods have to start by "on" followed by the event name without the double ":".
Example 13.5. Plugin class with event callback methods
class DbPlugin
{
public static onAtomikDispatchStart()
{
// listener for Atomik::Dispatch::Start
}
}
You can prevent automatic callback registration by returning false in the start method.
It is of course possible to load plugins at runtime. This is done using the Atomik::loadPlugin()
method.
To provide some configuration for the plugin, pass an array as the second argument.
Example 13.7. Loading a plugin at runtime with some configuration
Atomik::loadPlugin('Db', array('dbname' => 'test'));
You can check if a plugin is already loaded using Atomik::isPluginLoaded().
Atomik::loadPlugin() provides more advanced features which allow you for example
to create plugins for your plugin!
Example 13.9. More advance use of Atomik::loadPlugin()
// load plugins from a custom directory
Atomik::loadPlugin('MyPlugin', array(), '/custom/plugins/directory');
// using a custom plugin class name (in this case the class name will be MyPluginCustomPlugin)
Atomik::loadPlugin('MyPlugin', array(), null, '%CustomPlugin');
// do not call the start() method when loading plugins
Atomik::loadPlugin('MyPlugin', array(), null, '%Plugin', false);