plugin_packages.md

Plugins

Since we want to claim that our application supports plugins, we absolutely need a bit of plugin management.

As we already have Hooks and Events, we can freely use them in the plugins. We're set for building something interesting.

Structure

Plugins are composed by at least two files: composer.json and bootstrap.php. A third file may be automatically created for performance purposes, called composer.php containing the composer.json data. You can use the directory for anything else.

You will be able to choose multiple named directories to store the plugins. In general, this is the structure: plugins_folder/vendor_name/plugin_name In example, one of our plugins would be in plugins/foolz/fake.

composer.json

In example: plugins_folder/vendor_name/plugin_name/composer.json

You can describe the plugin with the structure of the composer.json file: it contains all that we need to describe a package. We make one single addition to improve functionality:

{
	"extra" : {
		"revision" : 0
	}
}

This allows setting a revision, used for database migrations. It's not compulsory to add this line to the composer.json, only add it when you need migrations. Use the extra section of composer.json to set your own plugin data. The Plugin class will be able to read that data.

bootstrap.php

In example: plugins_folder/vendor_name/plugin_name/bootstrap.php

This will be run every time you execute() the plugin. If you have a plugin called foolz/fake, it's structure may be the following:

<?php
	// execute
	\Event::forge('\foolz\plugin\plugin.execute.foolz/fake')
		->setCall(function($result){

		});

	// install
	\Event::forge('\foolz\plugin\plugin.install.foolz/fake')
		->setCall(function($result){

		});

	// uninstall
	\Event::forge('\foolz\plugin\plugin.uninstall.foolz/fake')
		->setCall(function($result){

		});

	// upgrade
	\Event::forge('\foolz\plugin\plugin.upgrade.foolz/fake')
		->setCall(function($result){
			$old_revision = $result->getParam('old_revision');
			$new_revision = $result->getParam('new_revision');
		});

It's not necessary to add all of them to bootstrap.php. Inside the closures you should insert your bootstrapping code for the plugin, and that should be mainly two things:

• Setting Events
• Setting Classes for autoloading

At the time of writing this, the package doesn't support PSR-0 loading. You can still use the class autoloading functions to define the location of your classes. This will keep working even after we add PSR-0 autoloading.

The install event is meant to migrate to the latest revision of the database and file schema. Keep the install always to the latest version so it doesn't require migrations. The upgrade event gets two parameters: old_revision and new_revision. You can use these to determine which migration actions the plugin should take. The uninstall event is meant to revert the changes made by the plugin to the system.

Loader

This class gives easy access to the arrays of plugins.

new Loader()

Instantiation.

Loader::forge($instance = 'default')

Creates or returns an instance of Loader.

• string $instance - The name of the instance

Chainable

Loader::destroy($instance = 'default')

Destroys an instance

• string $instance - The name of the instance

->addDir($dir_name, $dir = null)

Sets a named director where to look for the plugins.

• string $dir_name - An unique name for the directory. If only this is declared it should be the path. $dir_name and $dir will then be the same.
• string $dir - The path to the plugin folder

Chainable

->removeDir($dir_name)

Removes a dir in which plugins are looked into and unsets all the plugins loaded from that dir

• string $dir_name - The named dir to remove

Chainable

->getPlugins($dir_name = null)

Returns all the plugins.

• string $dir_name - If set it will only return the plugins from the named directory

Returns: array - an associative array of \Foolz\Plugin\Plugin with the dir name as first key and the plugin name as second. Only the plugin name as key if the dir name is set.

->getPlugin($dir_name, $slug)

Returns the plugin.

• string $dir_name - The named dir where the plugin is found
• string $slug - The name of the plugin

Returns: \Foolz\Plugin\Plugin - The selected plugin

---

Plugin

Each plugin is handled with a Plugin object.

->getDir()

Returns the path to the directory where the plugin is located.

Returns: string the path to the plugin directory

->addClass($class, $path)

Sets a class path for the autoloader.

• string $class - The class name
• string $path - The path to the class

Chainable

->removeClass($class)

Removes the class from the autoloading array.

• string $class - The class name

Chainable

->getConfig($section = null, $fallback = \Foolz\Plugin\Void)

Gets the configuration array or just a section.

• null|string section - An eventual string with arrays keys separated by dots
• mixed $fallback A fallback if the key is not found

Throws: \DomainException - if the fallback was still \Foolz\Plugin\Void and the key was not found

->getJsonConfig($section = null, $fallback = \Foolz\Plugin\Void)

Works as ->getConfig() but retrieves the data from the JSON file, therefore slower.

See: ->getConfig()

->execute()

Loads the bootstrap.php file and executes the event foolz\plugin\plugin.execute.vendor_name/plugin_name.

->install()

Loads the bootstrap.php file and executes the event foolz\plugin\plugin.install.vendor_name/plugin_name.

This method supposes that the original plugin files are already in place.

->uninstall()

Loads the bootstrap.php file and executes the event foolz\plugin\plugin.uninstall.vendor_name/plugin_name.

This method won't remove your plugin directory, only uninstall it with your Event.

->upgrade()

Loads the bootstrap.php file and executes the event foolz\plugin\plugin.upgrade.vendor_name/plugin_name.

This method should be run after you updated the files. You must leave the composer.php file in place to be able to have the plugin determine the revision. It will be updated by this method when the upgrade is done.