Pico/lib/PicoPluginInterface.php

106 lines
3.4 KiB
PHP
Raw Normal View History

2015-09-15 11:20:52 +00:00
<?php
/**
* This file is part of Pico. It's copyrighted by the contributors recorded
* in the version control history of the file, available from the following
* original location:
*
* <https://github.com/picocms/Pico/blob/master/lib/PicoPluginInterface.php>
*
* SPDX-License-Identifier: MIT
* License-Filename: LICENSE
*/
2015-09-15 11:20:52 +00:00
/**
* Common interface for Pico plugins
*
2017-05-13 16:17:58 +00:00
* For a list of supported events see {@see DummyPlugin}; you can use
* {@see DummyPlugin} as template for new plugins. For a list of deprecated
* events see {@see PicoDeprecated}.
2015-09-15 11:20:52 +00:00
*
2017-08-05 00:49:58 +00:00
* If you're developing a new plugin, you MUST both implement this interface
* and define the class constant `API_VERSION`. You SHOULD always use the
* API version of Pico's latest milestone when releasing a plugin. If you're
* developing a new version of an existing plugin, it is strongly recommended
* to update your plugin to use Pico's latest API version.
2015-09-15 11:20:52 +00:00
*
* @author Daniel Rudolf
* @link http://picocms.org
2016-05-23 13:13:56 +00:00
* @license http://opensource.org/licenses/MIT The MIT License
2019-11-11 18:02:11 +00:00
* @version 2.1
2015-09-15 11:20:52 +00:00
*/
interface PicoPluginInterface
{
/**
* Handles a event that was triggered by Pico
*
* @param string $eventName name of the triggered event
* @param array $params passed parameters
2015-09-15 11:20:52 +00:00
*/
public function handleEvent($eventName, array $params);
/**
* Enables or disables this plugin
*
* @see PicoPluginInterface::isEnabled()
* @see PicoPluginInterface::isStatusChanged()
*
* @param bool $enabled enable (TRUE) or disable (FALSE) this plugin
* @param bool $recursive when TRUE, enable or disable recursively.
2015-09-15 11:20:52 +00:00
* In other words, if you enable a plugin, all required plugins are
* enabled, too. When disabling a plugin, all depending plugins are
* disabled likewise. Recursive operations are only performed as long
* as a plugin wasn't enabled/disabled manually. This parameter is
* optional and defaults to TRUE.
* @param bool $auto enable or disable to fulfill a dependency. This
* parameter is optional and defaults to FALSE.
*
* @throws RuntimeException thrown when a dependency fails
2015-09-15 11:20:52 +00:00
*/
public function setEnabled($enabled, $recursive = true, $auto = false);
/**
* Returns a boolean indicating whether this plugin is enabled or not
*
* You musn't rely on the return value when Pico's `onConfigLoaded` event
* wasn't triggered on all plugins yet. This method might even return NULL
* then. The plugin's status might change later.
*
* @see PicoPluginInterface::setEnabled()
2015-09-15 11:20:52 +00:00
*
* @return bool|null plugin is enabled (TRUE) or disabled (FALSE)
2015-09-15 11:20:52 +00:00
*/
public function isEnabled();
/**
* Returns TRUE if the plugin was ever enabled/disabled manually
2015-09-15 11:20:52 +00:00
*
* @see PicoPluginInterface::setEnabled()
*
* @return bool plugin is in its default state (TRUE), FALSE otherwise
2015-09-15 11:20:52 +00:00
*/
public function isStatusChanged();
/**
* Returns a list of names of plugins required by this plugin
*
* @return string[] required plugins
2015-09-15 11:20:52 +00:00
*/
public function getDependencies();
/**
* Returns a list of plugins which depend on this plugin
*
* @return object[] dependant plugins
2015-09-15 11:20:52 +00:00
*/
public function getDependants();
/**
2019-09-11 10:07:48 +00:00
* Returns the plugin's instance of Pico
2015-09-15 11:20:52 +00:00
*
* @see Pico
*
2019-09-11 10:07:48 +00:00
* @return Pico the plugin's instance of Pico
2015-09-15 11:20:52 +00:00
*/
public function getPico();
}