Chapter 13. Plugins

Table of Contents

Using plugins
Installing a plugin
Activating and configuring a plugin
Developing plugins
The plugin file
Plugin's custom configuration
Using a class
Loading plugins programmaticaly
Plugin's assets

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.

Using plugins

Installing a plugin

Plugins are stored in the app/plugins directory. Simply copy the plugin file or folder into this directory.

Activating and configuring a plugin

Plugins are not automatically activated. To do so, it's needed to add an entry in the “plugins” configuration key.

Example 13.1. Activating a plugin

					
Atomik::set('plugins', array(
	'Db',
	'Cache'
));
				

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'
));
				

Developing plugins

The plugin file

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.

Note

To build more complex plugins you can instead of a file create a folder named after your plugin. Your php file goes into that folder and must be named Plugin.php.

When using folders, it is possible to add a sub folder named libraries which will automatically be added to php's include_path.

Plugin's custom configuration

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'];
				

Using a class

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.

Loading plugins programmaticaly

It is of course possible to load plugins at runtime. This is done using the Atomik::loadPlugin() method.

Example 13.6. Loading a plugin at runtime

				
Atomik::loadPlugin('Db');
			

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'));
			

Note

Be aware that some plugins may need to listen to some specific events. If you register your plugin too late, the event may have already occured, making the plugin malfunction.

You can check if a plugin is already loaded using Atomik::isPluginLoaded().

Example 13.8. Checking if a plugin is already loaded

				
if (Atomik::isPluginLoaded('Db')) {
	// ...
}
			

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);
			

Plugin's assets

When using the default .htaccess file, plugins can have an assets folder which is accessible from the Web. Of course, to use this folder, the plugin must come as a folder (see the note in the plugin file section).

Atomik also provides a method to obtain the url to asset files: Atomik::pluginAsset(). This method works using a template defined in “atomik/plugin_assets_tpl”. The default is “app/plugins/%s/assets”. The “%s” sign will be replaced with the plugin name.

The method takes as first argument the plugin name and as second the filename relative to the plugin's assets folder.

Example 13.10. Using Atomik::pluginAsset()

				
echo Atomik::pluginAsset('MyPlugin', 'css/styles.css');
// will output app/plugins/MyPlugin/assets/css/styles.css

Atomik::set('atomik/plugin_assets_tpl', 'plugins/%s/assets');
echo Atomik::pluginAsset('MyPlugin', 'css/styles.css');
// will output plugins/MyPlugin/assets/css/styles.css
			

Note

It is not adviced to change the plugin's assets folder name as some plugins may not work with your installation.