Any plugin that wants to add event observers to one of Piwik's {@hook # hooks},
or has special installation/uninstallation logic must implement this class.
Plugins that can specify everything they need to in the _plugin.json_ files,
such as themes, don't need to implement this class.
Class implementations should be named after the plugin they are a part of
(eg, class UserCountry extends Plugin).
### Plugin Metadata
In addition to providing a place for plugins to install/uninstall themselves
and add event observers, this class is also responsible for loading metadata
found in the plugin.json file.
The plugin.json file must exist in the root directory of a plugin. It can
contain the following information:
- **description**: An internationalized string description of what the plugin
does.
- **homepage**: The URL to the plugin's website.
- **authors**: A list of author arrays with keys for 'name', 'email' and 'homepage'
- **license**: The license the code uses (eg, GPL, MIT, etc.).
- **license_homepage**: URL to website describing the license used.
- **version**: The plugin version (eg, 1.0.1).
- **theme**: true or false. If true, the plugin will be treated as a theme.
### Examples
**How to extend**
use Piwik\Common;
use Piwik\Plugin;
use Piwik\Db;
class MyPlugin extends Plugin
{
public function getListHooksRegistered()
{
return array(
'API.getReportMetadata' => 'getReportMetadata',
'Another.event' => array(
'function' => 'myOtherPluginFunction',
'after' => true // executes this callback after others
)
);
}
public function install()
{
Db::exec("CREATE TABLE " . Common::prefixTable('mytable') . "...");
}
public function uninstall()
{
Db::exec("DROP TABLE IF EXISTS " . Common::prefixTable('mytable'));
}
public function getReportMetadata(&$metadata)
{
...
}
public function myOtherPluginFunction()
{
...
}
}
private function getVersion($component)
{
if ($component === 'core') {
return Version::VERSION;
}
$pluginManager = Plugin\Manager::getInstance();
if ($pluginManager->isPluginLoaded($component)) {
$plugin = $pluginManager->getLoadedPlugin($component);
} else {
$plugin = new Plugin($component);
}
return $plugin->getVersion();
}
public function getInformation()
{
$info = parent::getInformation();
$info['author'] = 'Piwik PRO';
$info['author_homepage'] = 'http://piwik.pro';
return $info;
}
public function getInformation()
{
$suffix = ' Note: Requires the Transitions plugin enabled.';
$info = parent::getInformation();
$info['description'] .= ' ' . $suffix;
return $info;
}
public function getInformation()
{
$suffix = Piwik::translate('SitesManager_PiwikOffersEcommerceAnalytics', array('<a href="http://piwik.org/docs/ecommerce-analytics/" target="_blank">', '</a>'));
$info = parent::getInformation();
$info['description'] .= ' ' . $suffix;
return $info;
}
public function getInformation()
{
$suffix = ' Debug: <a href="' . Url::getCurrentQueryStringWithParametersModified(array('module' => 'ImageGraph', 'action' => 'index')) . '">All images</a>';
$info = parent::getInformation();
$info['description'] .= ' ' . $suffix;
return $info;
}
public function getJavaScriptFiles()
{
if ($this->themeName == \Piwik\Plugin\Manager::DEFAULT_THEME) {
return false;
}
$info = $this->theme->getInformation();
if (empty($info['javascript'])) {
return false;
}
$jsFiles = $info['javascript'];
if (!is_array($jsFiles)) {
$jsFiles = array($jsFiles);
}
foreach ($jsFiles as &$jsFile) {
$jsFile = 'plugins/' . $this->theme->getPluginName() . '/' . $jsFile;
}
return $jsFiles;
}
/**
* Returns the name of the plugin/class that triggered the log.
*
* @return string
*/
private function getLoggingClassName()
{
$backtrace = $this->getBacktrace();
$name = Plugin::getPluginNameFromBacktrace($backtrace);
// if we can't determine the plugin, use the name of the calling class
if ($name == false) {
$name = $this->getClassNameThatIsLogging($backtrace);
}
return $name;
}
/**
* Install a plugin, if necessary
*
* @param Plugin $plugin
*/
private function installPluginIfNecessary(Plugin $plugin)
{
$pluginName = $plugin->getPluginName();
$saveConfig = false;
// is the plugin already installed or is it the first time we activate it?
$pluginsInstalled = $this->getInstalledPluginsName();
if (!$this->isPluginInstalled($pluginName)) {
$this->executePluginInstall($plugin);
$pluginsInstalled[] = $pluginName;
$this->updatePluginsInstalledConfig($pluginsInstalled);
$updater = new Updater();
$updater->markComponentSuccessfullyUpdated($plugin->getPluginName(), $plugin->getVersion());
$saveConfig = true;
}
if ($saveConfig) {
PiwikConfig::getInstance()->forceSave();
}
}
public function isTrackerPlugin(Plugin $plugin)
{
$hooks = $plugin->getListHooksRegistered();
$hookNames = array_keys($hooks);
foreach ($hookNames as $name) {
if (strpos($name, self::TRACKER_EVENT_PREFIX) === 0) {
return true;
}
if ($name === 'Request.initAuthenticationObject') {
return true;
}
}
return false;
}
public static function loadAllPlugins($testEnvironment = null, $testCaseClass = false, $extraPluginsToLoad = array())
{
if (empty($testEnvironment)) {
$testEnvironment = new Piwik_TestingEnvironment();
}
DbHelper::createTables();
$pluginsManager = \Piwik\Plugin\Manager::getInstance();
$plugins = $testEnvironment->getCoreAndSupportedPlugins();
// make sure the plugin that executed this method is included in the plugins to load
$extraPlugins = array_merge($extraPluginsToLoad, array(\Piwik\Plugin::getPluginNameFromBacktrace(debug_backtrace()), \Piwik\Plugin::getPluginNameFromNamespace($testCaseClass), \Piwik\Plugin::getPluginNameFromNamespace(get_called_class())));
foreach ($extraPlugins as $pluginName) {
if (empty($pluginName)) {
continue;
}
if (in_array($pluginName, $plugins)) {
continue;
}
$plugins[] = $pluginName;
if ($testEnvironment) {
$testEnvironment->pluginsToLoad = array_merge($testEnvironment->pluginsToLoad ?: array(), array($pluginName));
}
}
Log::debug("Plugins to load during tests: " . implode(', ', $plugins));
$pluginsManager->loadPlugins($plugins);
}
public function getDbName()
{
if ($this->dbName !== false) {
return $this->dbName;
}
if ($this->persistFixtureData) {
$klass = new ReflectionClass($this);
$id = Plugin::getPluginNameFromNamespace($klass->getNamespaceName()) . "_" . $klass->getShortName();
return $id;
}
return self::getConfig()->database_tests['dbname'];
}
public function getThemeName()
{
return $this->plugin->getPluginName();
}
/**
* create template loader for a custom theme
* @param \Piwik\Plugin $theme
* @return \Twig_Loader_Filesystem
*/
protected function getCustomThemeLoader(Plugin $theme)
{
if (!file_exists(sprintf("%s/plugins/%s/templates/", PIWIK_INCLUDE_PATH, $theme->getPluginName()))) {
return false;
}
$themeLoader = new Twig_Loader_Filesystem(array(sprintf("%s/plugins/%s/templates/", PIWIK_INCLUDE_PATH, $theme->getPluginName())));
return $themeLoader;
}
/**
* Constructor.
*/
public function __construct()
{
parent::__construct();
$this->dntChecker = new DoNotTrackHeaderChecker();
$this->ipAnonymizer = new IPAnonymizer();
}
protected function isTrackerPlugin(Plugin $plugin)
{
$hooks = $plugin->getListHooksRegistered();
$hookNames = array_keys($hooks);
foreach ($hookNames as $name) {
if (strpos($name, self::TRACKER_EVENT_PREFIX) === 0) {
return true;
}
}
return false;
}
/**
* @param Plugin $plugin
*/
private function createThemeFromPlugin($plugin)
{
$this->theme = $plugin;
$this->themeName = $plugin->getPluginName();
}
/**
* Get all lo that are defined by the given plugin.
*
* @param Plugin $plugin
* @return LocationProvider[]
*/
protected static function getLocationProviders(Plugin $plugin)
{
$locationProviders = $plugin->findMultipleComponents('LocationProvider', 'Piwik\\Plugins\\UserCountry\\LocationProvider');
$instances = [];
foreach ($locationProviders as $locationProvider) {
$instances[] = new $locationProvider();
}
return $instances;
}
public function getInformation()
{
$info = parent::getInformation();
$info['description'] .= ' <br/>Required to use <a href="http://piwik.org/docs/ecommerce-analytics/">Ecommerce Analytics</a> feature!';
return $info;
}
public function isTrackerPlugin(Plugin $plugin)
{
if (!$this->isPluginInstalled($plugin->getPluginName())) {
return false;
}
if ($plugin->isTrackerPlugin()) {
return true;
}
$dimensions = VisitDimension::getDimensions($plugin);
if (!empty($dimensions)) {
return true;
}
$dimensions = ActionDimension::getDimensions($plugin);
if (!empty($dimensions)) {
return true;
}
$hooks = $plugin->getListHooksRegistered();
$hookNames = array_keys($hooks);
foreach ($hookNames as $name) {
if (strpos($name, self::TRACKER_EVENT_PREFIX) === 0) {
return true;
}
if ($name === 'Request.initAuthenticationObject') {
return true;
}
}
$dimensions = ConversionDimension::getDimensions($plugin);
if (!empty($dimensions)) {
return true;
}
return false;
}
/**
* Constructor.
*/
public function __construct()
{
parent::__construct();
$this->configuration = new Configuration();
}
private function doLog($level, $message, $sprintfParams = array())
{
if (!$this->shouldLoggerLog($level)) {
return;
}
$datetime = date("Y-m-d H:i:s");
if (is_string($message) && !empty($sprintfParams)) {
$message = vsprintf($message, $sprintfParams);
}
if (version_compare(phpversion(), '5.3.6', '>=')) {
$backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS | DEBUG_BACKTRACE_PROVIDE_OBJECT);
} else {
$backtrace = debug_backtrace();
}
$tag = Plugin::getPluginNameFromBacktrace($backtrace);
// if we can't determine the plugin, use the name of the calling class
if ($tag == false) {
$tag = $this->getClassNameThatIsLogging($backtrace);
}
$this->writeMessage($level, $tag, $datetime, $message);
}
/**
* Get all action dimensions that are defined by the given plugin.
* @param Plugin $plugin
* @return ActionDimension[]
* @ignore
*/
public static function getDimensions(Plugin $plugin)
{
$dimensions = $plugin->findMultipleComponents('Columns', '\\Piwik\\Plugin\\Dimension\\ActionDimension');
$instances = array();
foreach ($dimensions as $dimension) {
$instances[] = new $dimension();
}
return $instances;
}
public function __construct()
{
parent::__construct();
$this->osRelatedReports = array('DevicesDetection.getOsFamilies' => Piwik::translate('DevicesDetection_OperatingSystemFamilies'), 'DevicesDetection.getOsVersions' => Piwik::translate('DevicesDetection_OperatingSystemVersions'));
$this->browserRelatedReports = array('DevicesDetection.getBrowserFamilies' => Piwik::translate('UserSettings_BrowserFamilies'), 'DevicesDetection.getBrowserVersions' => Piwik::translate('DevicesDetection_BrowserVersions'));
}
private function getPluginsToLoadDuringTest()
{
$plugins = $this->vars->getCoreAndSupportedPlugins();
// make sure the plugin that executed this method is included in the plugins to load
$extraPlugins = array_merge(self::$extraPluginsToLoad, $this->vars->pluginsToLoad ?: array(), array(Plugin::getPluginNameFromBacktrace(debug_backtrace()), Plugin::getPluginNameFromNamespace($this->vars->testCaseClass), Plugin::getPluginNameFromNamespace($this->vars->fixtureClass), Plugin::getPluginNameFromNamespace(get_called_class())));
foreach ($extraPlugins as $pluginName) {
if (empty($pluginName)) {
continue;
}
if (in_array($pluginName, $plugins)) {
continue;
}
$plugins[] = $pluginName;
}
return $plugins;
}
public function __construct()
{
// this class is named 'Plugin', manually set the 'API' plugin
parent::__construct($pluginName = 'API');
}
public function getInformation()
{
$info = parent::getInformation();
$info['authors'] = array(array('name' => 'Piwik PRO', 'homepage' => 'http://piwik.pro'));
return $info;
}
/**
* Install a plugin, if necessary
*
* @param Plugin $plugin
*/
private function installPluginIfNecessary(Plugin $plugin)
{
$pluginName = $plugin->getPluginName();
$saveConfig = false;
// is the plugin already installed or is it the first time we activate it?
$pluginsInstalled = $this->getInstalledPluginsName();
if (!$this->isPluginInstalled($pluginName)) {
$this->executePluginInstall($plugin);
$pluginsInstalled[] = $pluginName;
$this->updatePluginsInstalledConfig($pluginsInstalled);
Updater::recordComponentSuccessfullyUpdated($plugin->getPluginName(), $plugin->getVersion());
$saveConfig = true;
}
if ($this->isTrackerPlugin($plugin)) {
$pluginsTracker = PiwikConfig::getInstance()->Plugins_Tracker['Plugins_Tracker'];
if (is_null($pluginsTracker)) {
$pluginsTracker = array();
}
if (!in_array($pluginName, $pluginsTracker)) {
$pluginsTracker[] = $pluginName;
$this->updatePluginsTrackerConfig($pluginsTracker);
$saveConfig = true;
}
}
if ($saveConfig) {
PiwikConfig::getInstance()->forceSave();
}
}
