Plugin.php — Matomo Analytics – Powerful, Privacy-First Insights for WordPress 5.0.7

matomo / app / core / Plugin.php

matomo / app / core Last commit date

API 2 years ago Access 2 years ago Application 2 years ago Archive 2 years ago ArchiveProcessor 2 years ago Archiver 2 years ago AssetManager 2 years ago Auth 2 years ago Category 2 years ago Changes 2 years ago CliMulti 2 years ago Columns 2 years ago Concurrency 2 years ago Config 2 years ago Container 2 years ago CronArchive 2 years ago DataAccess 2 years ago DataFiles 2 years ago DataTable 2 years ago Db 2 years ago DeviceDetector 2 years ago Email 2 years ago Exception 2 years ago Http 2 years ago Intl 2 years ago Log 2 years ago Mail 2 years ago Measurable 2 years ago Menu 2 years ago Metrics 2 years ago Notification 2 years ago Period 2 years ago Plugin 2 years ago ProfessionalServices 2 years ago Report 2 years ago ReportRenderer 2 years ago Scheduler 2 years ago Segment 2 years ago Session 2 years ago Settings 2 years ago Tracker 2 years ago Translation 2 years ago Twig 2 years ago UpdateCheck 2 years ago Updater 2 years ago Updates 2 years ago Validators 2 years ago View 2 years ago ViewDataTable 2 years ago Visualization 2 years ago Widget 2 years ago .htaccess 2 years ago Access.php 2 years ago Archive.php 2 years ago ArchiveProcessor.php 2 years ago AssetManager.php 2 years ago Auth.php 2 years ago AuthResult.php 2 years ago BaseFactory.php 2 years ago Cache.php 2 years ago CacheId.php 2 years ago CliMulti.php 2 years ago Common.php 2 years ago Config.php 2 years ago Console.php 2 years ago Context.php 2 years ago Cookie.php 2 years ago CronArchive.php 2 years ago DI.php 2 years ago DataArray.php 2 years ago DataTable.php 2 years ago Date.php 2 years ago Db.php 2 years ago DbHelper.php 2 years ago Development.php 2 years ago ErrorHandler.php 2 years ago EventDispatcher.php 2 years ago ExceptionHandler.php 2 years ago FileIntegrity.php 2 years ago Filechecks.php 2 years ago Filesystem.php 2 years ago FrontController.php 2 years ago Http.php 2 years ago IP.php 2 years ago Log.php 2 years ago LogDeleter.php 2 years ago Mail.php 2 years ago Metrics.php 2 years ago NoAccessException.php 2 years ago Nonce.php 2 years ago Notification.php 2 years ago NumberFormatter.php 2 years ago Option.php 2 years ago Period.php 2 years ago Piwik.php 2 years ago Plugin.php 2 years ago Profiler.php 2 years ago ProxyHeaders.php 2 years ago ProxyHttp.php 2 years ago QuickForm2.php 2 years ago RankingQuery.php 2 years ago ReportRenderer.php 2 years ago Request.php 2 years ago Segment.php 2 years ago Sequence.php 2 years ago Session.php 2 years ago SettingsPiwik.php 2 years ago SettingsServer.php 2 years ago Singleton.php 2 years ago Site.php 2 years ago SiteContentDetector.php 2 years ago SupportedBrowser.php 2 years ago TCPDF.php 2 years ago Theme.php 2 years ago Timer.php 2 years ago Tracker.php 2 years ago Twig.php 2 years ago Unzip.php 2 years ago UpdateCheck.php 2 years ago Updater.php 2 years ago UpdaterErrorException.php 2 years ago Updates.php 2 years ago Url.php 2 years ago UrlHelper.php 2 years ago Version.php 2 years ago View.php 2 years ago bootstrap.php 2 years ago dispatch.php 2 years ago testMinimumPhpVersion.php 2 years ago

Plugin.php

610 lines

1	<?php
2
3	/**
4	* Matomo - free/libre analytics platform
5	*
6	* @link https://matomo.org
7	* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
8	*
9	*/
10	namespace Piwik;
11
12	use Piwik\Archive\ArchiveInvalidator;
13	use Piwik\Container\StaticContainer;
14	use Piwik\Plugin\Dependency;
15	use Piwik\Plugin\Manager;
16	use Piwik\Plugin\MetadataLoader;
17	if (!class_exists('Piwik\\Plugin')) {
18	/**
19	* Base class of all Plugin Descriptor classes.
20	*
21	* Any plugin that wants to add event observers to one of Piwik's {@hook # hooks},
22	* or has special installation/uninstallation logic must implement this class.
23	* Plugins that can specify everything they need to in the _plugin.json_ files,
24	* such as themes, don't need to implement this class.
25	*
26	* Class implementations should be named after the plugin they are a part of
27	* (eg, `class UserCountry extends Plugin`).
28	*
29	* ### Plugin Metadata
30	*
31	* In addition to providing a place for plugins to install/uninstall themselves
32	* and add event observers, this class is also responsible for loading metadata
33	* found in the plugin.json file.
34	*
35	* The plugin.json file must exist in the root directory of a plugin. It can
36	* contain the following information:
37	*
38	* - description: An internationalized string description of what the plugin
39	* does.
40	* - homepage: The URL to the plugin's website.
41	* - authors: A list of author arrays with keys for 'name', 'email' and 'homepage'
42	* - license: The license the code uses (eg, GPL, MIT, etc.).
43	* - version: The plugin version (eg, 1.0.1).
44	* - theme: `true` or `false`. If `true`, the plugin will be treated as a theme.
45	*
46	* ### Examples
47	*
48	* How to extend
49	*
50	* use Piwik\Common;
51	* use Piwik\Plugin;
52	* use Piwik\Db;
53	*
54	* class MyPlugin extends Plugin
55	* {
56	* public function registerEvents()
57	* {
58	* return array(
59	* 'API.getReportMetadata' => 'getReportMetadata',
60	* 'Another.event' => array(
61	* 'function' => 'myOtherPluginFunction',
62	* 'after' => true // executes this callback after others
63	* )
64	* );
65	* }
66	*
67	* public function install()
68	* {
69	* Db::exec("CREATE TABLE " . Common::prefixTable('mytable') . "...");
70	* }
71	*
72	* public function uninstall()
73	* {
74	* Db::exec("DROP TABLE IF EXISTS " . Common::prefixTable('mytable'));
75	* }
76	*
77	* public function getReportMetadata(&$metadata)
78	* {
79	* // ...
80	* }
81	*
82	* public function myOtherPluginFunction()
83	* {
84	* // ...
85	* }
86	* }
87	*
88	* @api
89	*/
90	class Plugin
91	{
92	/**
93	* Name of this plugin.
94	*
95	* @var string
96	*/
97	protected $pluginName;
98	/**
99	* Holds plugin metadata.
100	*
101	* @var array
102	*/
103	private $pluginInformation;
104	/**
105	* As the cache is used quite often we avoid having to create instances all the time. We reuse it which is not
106	* perfect but efficient. If the cache is used we need to make sure to call setId() before usage as there
107	* is maybe a different key set since last usage.
108	*
109	* @var \Matomo\Cache\Eager
110	*/
111	private $cache;
112	/**
113	* Constructor.
114	*
115	* @param string\|bool $pluginName A plugin name to force. If not supplied, it is set
116	* to the last part of the class name.
117	* @throws \Exception If plugin metadata is defined in both the getInformation() method
118	* and the plugin.json file.
119	*/
120	public function __construct($pluginName = false)
121	{
122	if (empty($pluginName)) {
123	$pluginName = explode('\\', get_class($this));
124	$pluginName = end($pluginName);
125	}
126	$this->pluginName = $pluginName;
127	$cacheId = 'Plugin' . $pluginName . 'Metadata';
128	$cache = \Piwik\Cache::getEagerCache();
129	if ($cache->contains($cacheId)) {
130	$this->pluginInformation = $cache->fetch($cacheId);
131	} else {
132	$this->reloadPluginInformation();
133	$cache->save($cacheId, $this->pluginInformation);
134	}
135	}
136	public function reloadPluginInformation()
137	{
138	$metadataLoader = new MetadataLoader($this->pluginName);
139	$this->pluginInformation = $metadataLoader->load();
140	if ($this->hasDefinedPluginInformationInPluginClass() && $metadataLoader->hasPluginJson()) {
141	throw new \Exception('Plugin ' . $this->pluginName . ' has defined the method getInformation() and as well as having a plugin.json file. Please delete the getInformation() method from the plugin class. Alternatively, you may delete the plugin directory from plugins/' . $this->pluginName);
142	}
143	}
144	private function createCacheIfNeeded()
145	{
146	if (is_null($this->cache)) {
147	$this->cache = \Piwik\Cache::getEagerCache();
148	}
149	}
150	private function hasDefinedPluginInformationInPluginClass()
151	{
152	$myClassName = \Piwik\Plugin::class;
153	$pluginClassName = get_class($this);
154	if ($pluginClassName == $myClassName) {
155	// plugin has not defined its own class
156	return false;
157	}
158	$foo = new \ReflectionMethod(get_class($this), 'getInformation');
159	$declaringClass = $foo->getDeclaringClass()->getName();
160	return $declaringClass != $myClassName;
161	}
162	/**
163	* Returns plugin information, including:
164	*
165	* - 'description' => string // 1-2 sentence description of the plugin
166	* - 'author' => string // plugin author
167	* - 'author_homepage' => string // author homepage URL (or email "mailto:youremail@example.org")
168	* - 'homepage' => string // plugin homepage URL
169	* - 'license' => string // plugin license
170	* - 'version' => string // plugin version number; examples and 3rd party plugins must not use Version::VERSION; 3rd party plugins must increment the version number with each plugin release
171	* - 'theme' => bool // Whether this plugin is a theme (a theme is a plugin, but a plugin is not necessarily a theme)
172	*
173	* @return array
174	*/
175	public function getInformation()
176	{
177	return $this->pluginInformation;
178	}
179	public final function isPremiumFeature()
180	{
181	return !empty($this->pluginInformation['price']['base']);
182	}
183	/**
184	* Return true here if you want your plugin's Vue module to be loaded on demand, when it is first
185	* referenced, rather than on page load. This can be used to improve initial page load time,
186	* especially if your plugin includes a lot of Vue code.
187	*
188	* Note: doing this means that any other plugins that depend on yours will no longer
189	* be able to do a normal `import ... from 'MyPlugin';`, they will instead have to
190	* use the `importPluginUmd()` function in `CoreHome` which returns a Promise.
191	*
192	* @return boolean
193	*/
194	public function shouldLoadUmdOnDemand()
195	{
196	return false;
197	}
198	/**
199	* Returns a list of events with associated event observers.
200	*
201	* Derived classes should use this method to associate callbacks with events.
202	*
203	* @return array eg,
204	*
205	* array(
206	* 'API.getReportMetadata' => 'myPluginFunction',
207	* 'Another.event' => array(
208	* 'function' => 'myOtherPluginFunction',
209	* 'after' => true // execute after callbacks w/o ordering
210	* )
211	* 'Yet.Another.event' => array(
212	* 'function' => 'myOtherPluginFunction',
213	* 'before' => true // execute before callbacks w/o ordering
214	* )
215	* )
216	* @since 2.15.0
217	*/
218	public function registerEvents()
219	{
220	return array();
221	}
222	/**
223	* This method is executed after a plugin is loaded and translations are registered.
224	* Useful for initialization code that uses translated strings.
225	*/
226	public function postLoad()
227	{
228	return;
229	}
230	/**
231	* Defines whether the whole plugin requires a working internet connection
232	* If set to true, the plugin will be automatically unloaded if `enable_internet_features` is 0,
233	* even if the plugin is activated
234	*
235	* @return bool
236	*/
237	public function requiresInternetConnection()
238	{
239	return false;
240	}
241	/**
242	* Installs the plugin. Derived classes should implement this class if the plugin
243	* needs to:
244	*
245	* - create tables
246	* - update existing tables
247	* - etc.
248	*
249	* @throws \Exception if installation of fails for some reason.
250	*/
251	public function install()
252	{
253	return;
254	}
255	/**
256	* Uninstalls the plugins. Derived classes should implement this method if the changes
257	* made in {@link install()} need to be undone during uninstallation.
258	*
259	* In most cases, if you have an {@link install()} method, you should provide
260	* an {@link uninstall()} method.
261	*
262	* @throws \Exception if uninstallation of fails for some reason.
263	*/
264	public function uninstall()
265	{
266	return;
267	}
268	/**
269	* Executed every time the plugin is enabled.
270	*/
271	public function activate()
272	{
273	return;
274	}
275	/**
276	* Executed every time the plugin is disabled.
277	*/
278	public function deactivate()
279	{
280	return;
281	}
282	/**
283	* Returns the plugin version number.
284	*
285	* @return string
286	*/
287	public final function getVersion()
288	{
289	$info = $this->getInformation();
290	return $info['version'];
291	}
292	/**
293	* Returns `true` if this plugin is a theme, `false` if otherwise.
294	*
295	* @return bool
296	*/
297	public function isTheme()
298	{
299	$info = $this->getInformation();
300	return !empty($info['theme']) && (bool) $info['theme'];
301	}
302	/**
303	* Returns the plugin's base class name without the namespace,
304	* e.g., `"UserCountry"` when the plugin class is `"Piwik\Plugins\UserCountry\UserCountry"`.
305	*
306	* @return string
307	*/
308	public final function getPluginName()
309	{
310	return $this->pluginName;
311	}
312	/**
313	* Tries to find a component such as a Menu or Tasks within this plugin.
314	*
315	* @param string $componentName The name of the component you want to look for. In case you request a
316	* component named 'Menu' it'll look for a file named 'Menu.php' within the
317	* root of the plugin folder that implements a class named
318	* Piwik\Plugin\$PluginName\Menu . If such a file exists but does not implement
319	* this class it'll silently ignored.
320	* @param string $expectedSubclass If not empty, a check will be performed whether a found file extends the
321	* given subclass. If the requested file exists but does not extend this class
322	* a warning will be shown to advice a developer to extend this certain class.
323	*
324	* @return string\|null Null if the requested component does not exist or an instance of the found
325	* component.
326	*/
327	public function findComponent($componentName, $expectedSubclass)
328	{
329	$this->createCacheIfNeeded();
330	$cacheId = 'Plugin' . $this->pluginName . $componentName . $expectedSubclass;
331	$pluginsDir = Manager::getPluginDirectory($this->pluginName);
332	$componentFile = sprintf('%s/%s.php', $pluginsDir, $componentName);
333	if ($this->cache->contains($cacheId)) {
334	$classname = $this->cache->fetch($cacheId);
335	if (empty($classname)) {
336	return null;
337	// might by "false" in case has no menu, widget, ...
338	}
339	if (file_exists($componentFile)) {
340	include_once $componentFile;
341	}
342	} else {
343	$this->cache->save($cacheId, false);
344	// prevent from trying to load over and over again for instance if there is no Menu for a plugin
345	if (!file_exists($componentFile)) {
346	return null;
347	}
348	require_once $componentFile;
349	$classname = sprintf('Piwik\\Plugins\\%s\\%s', $this->pluginName, $componentName);
350	if (!class_exists($classname)) {
351	return null;
352	}
353	if (!empty($expectedSubclass) && !is_subclass_of($classname, $expectedSubclass)) {
354	\Piwik\Log::warning(sprintf('Cannot use component %s for plugin %s, class %s does not extend %s', $componentName, $this->pluginName, $classname, $expectedSubclass));
355	return null;
356	}
357	$this->cache->save($cacheId, $classname);
358	}
359	return $classname;
360	}
361	public function findMultipleComponents($directoryWithinPlugin, $expectedSubclass)
362	{
363	$this->createCacheIfNeeded();
364	$cacheId = 'Plugin' . $this->pluginName . $directoryWithinPlugin . $expectedSubclass;
365	if ($this->cache->contains($cacheId)) {
366	$components = $this->cache->fetch($cacheId);
367	if ($this->includeComponents($components)) {
368	return $components;
369	} else {
370	// problem including one cached file, refresh cache
371	}
372	}
373	$components = $this->doFindMultipleComponents($directoryWithinPlugin, $expectedSubclass);
374	$this->cache->save($cacheId, $components);
375	return $components;
376	}
377	/**
378	* Detect whether there are any missing dependencies.
379	*
380	* @param null $piwikVersion Defaults to the current Piwik version
381	* @return bool
382	*/
383	public function hasMissingDependencies($piwikVersion = null)
384	{
385	$requirements = $this->getMissingDependencies($piwikVersion);
386	return !empty($requirements);
387	}
388	public function getMissingDependencies($piwikVersion = null)
389	{
390	if (empty($this->pluginInformation['require'])) {
391	return array();
392	}
393	$dependency = $this->makeDependency($piwikVersion);
394	return $dependency->getMissingDependencies($this->pluginInformation['require']);
395	}
396	/**
397	* Returns a string (translated) describing the missing requirements for this plugin and the given Piwik version
398	*
399	* @param string $piwikVersion
400	* @return string "AnonymousPiwikUsageMeasurement requires PIWIK >=3.0.0"
401	*/
402	public function getMissingDependenciesAsString($piwikVersion = null)
403	{
404	if ($this->requiresInternetConnection() && !\Piwik\SettingsPiwik::isInternetEnabled()) {
405	return \Piwik\Piwik::translate('CorePluginsAdmin_PluginRequiresInternet');
406	}
407	if (empty($this->pluginInformation['require'])) {
408	return '';
409	}
410	$dependency = $this->makeDependency($piwikVersion);
411	$missingDependencies = $dependency->getMissingDependencies($this->pluginInformation['require']);
412	if (empty($missingDependencies)) {
413	return '';
414	}
415	$causedBy = array();
416	foreach ($missingDependencies as $dependency) {
417	$causedBy[] = ucfirst($dependency['requirement']) . ' ' . $dependency['causedBy'];
418	}
419	return \Piwik\Piwik::translate("CorePluginsAdmin_PluginRequirement", array($this->getPluginName(), implode(', ', $causedBy)));
420	}
421	/**
422	* Schedules re-archiving of this plugin's reports from when this plugin was last
423	* deactivated to now. If the last time core:archive was run is earlier than the
424	* plugin's last deactivation time, then we use that time instead.
425	*
426	* Note: this only works for CLI archiving setups.
427	*
428	* Note: the time frame is limited by the `[General] rearchive_reports_in_past_last_n_months`
429	* INI config value.
430	*
431	* @throws \Piwik\Exception\DI\DependencyException
432	* @throws \Piwik\Exception\DI\NotFoundException
433	*/
434	public function schedulePluginReArchiving()
435	{
436	$lastDeactivationTime = $this->getPluginLastDeactivationTime();
437	$dateTime = null;
438	$lastCronArchiveTime = (int) \Piwik\Option::get(\Piwik\CronArchive::OPTION_ARCHIVING_FINISHED_TS);
439	if (empty($lastCronArchiveTime)) {
440	$dateTime = $lastDeactivationTime;
441	} else {
442	if (empty($lastDeactivationTime)) {
443	$dateTime = null;
444	// use default earliest time
445	} else {
446	$lastCronArchiveTime = \Piwik\Date::factory($lastCronArchiveTime);
447	$dateTime = $lastDeactivationTime->isEarlier($lastCronArchiveTime) ? $lastDeactivationTime : $lastCronArchiveTime;
448	}
449	}
450	if (empty($dateTime)) {
451	// sanity check
452	$dateTime = null;
453	}
454	$archiveInvalidator = StaticContainer::get(ArchiveInvalidator::class);
455	$archiveInvalidator->scheduleReArchiving('all', $this->getPluginName(), $report = null, $dateTime);
456	}
457	/**
458	* Extracts the plugin name from a backtrace array. Returns `false` if we can't find one.
459	*
460	* @param array $backtrace The result of {@link debug_backtrace()} or
461	* [Exception::getTrace()](http://www.php.net/manual/en/exception.gettrace.php).
462	* @return string\|false
463	*/
464	public static function getPluginNameFromBacktrace($backtrace)
465	{
466	foreach ($backtrace as $tracepoint) {
467	// try and discern the plugin name
468	if (isset($tracepoint['class'])) {
469	$className = self::getPluginNameFromNamespace($tracepoint['class']);
470	if ($className) {
471	return $className;
472	}
473	}
474	}
475	return false;
476	}
477	/**
478	* Extracts the plugin name from a namespace name or a fully qualified class name. Returns `false`
479	* if we can't find one.
480	*
481	* @param string $namespaceOrClassName The namespace or class string.
482	* @return string\|false
483	*/
484	public static function getPluginNameFromNamespace($namespaceOrClassName)
485	{
486	if ($namespaceOrClassName && preg_match("/Piwik\\\\Plugins\\\\([a-zA-Z_0-9]+)\\\\/", $namespaceOrClassName, $matches)) {
487	return $matches[1];
488	} else {
489	return false;
490	}
491	}
492	/**
493	* Override this method in your plugin class if you want your plugin to be loaded during tracking.
494	*
495	* Note: If you define your own dimension or handle a tracker event, your plugin will automatically
496	* be detected as a tracker plugin.
497	*
498	* @return bool
499	* @internal
500	*/
501	public function isTrackerPlugin()
502	{
503	return false;
504	}
505	/**
506	* @return Date\|null
507	* @throws \Exception
508	*/
509	public function getPluginLastActivationTime()
510	{
511	$optionName = Manager::LAST_PLUGIN_ACTIVATION_TIME_OPTION_PREFIX . $this->pluginName;
512	$time = \Piwik\Option::get($optionName);
513	if (empty($time)) {
514	return null;
515	}
516	return \Piwik\Date::factory((int) $time);
517	}
518	/**
519	* @return Date\|null
520	* @throws \Exception
521	*/
522	public function getPluginLastDeactivationTime()
523	{
524	$optionName = Manager::LAST_PLUGIN_DEACTIVATION_TIME_OPTION_PREFIX . $this->pluginName;
525	$time = \Piwik\Option::get($optionName);
526	if (empty($time)) {
527	return null;
528	}
529	return \Piwik\Date::factory((int) $time);
530	}
531	/**
532	* @param $directoryWithinPlugin
533	* @param $expectedSubclass
534	* @return array
535	*/
536	private function doFindMultipleComponents($directoryWithinPlugin, $expectedSubclass)
537	{
538	$components = array();
539	$pluginsDir = Manager::getPluginDirectory($this->pluginName);
540	$baseDir = $pluginsDir . '/' . $directoryWithinPlugin;
541	$files = \Piwik\Filesystem::globr($baseDir, '*.php');
542	foreach ($files as $file) {
543	require_once $file;
544	$fileName = str_replace(array($baseDir . '/', '.php'), '', $file);
545	$klassName = sprintf('Piwik\\Plugins\\%s\\%s\\%s', $this->pluginName, str_replace('/', '\\', $directoryWithinPlugin), str_replace('/', '\\', $fileName));
546	if (!class_exists($klassName)) {
547	continue;
548	}
549	if (!empty($expectedSubclass) && !is_subclass_of($klassName, $expectedSubclass)) {
550	continue;
551	}
552	$klass = new \ReflectionClass($klassName);
553	if ($klass->isAbstract()) {
554	continue;
555	}
556	$components[$file] = $klassName;
557	}
558	return $components;
559	}
560	/**
561	* @param $components
562	* @return bool true if all files were included, false if any file cannot be read
563	*/
564	private function includeComponents($components)
565	{
566	foreach ($components as $file => $klass) {
567	if (!is_readable($file)) {
568	return false;
569	}
570	}
571	foreach ($components as $file => $klass) {
572	include_once $file;
573	}
574	return true;
575	}
576	/**
577	* @param $piwikVersion
578	* @return Dependency
579	*/
580	private function makeDependency($piwikVersion)
581	{
582	$dependency = new Dependency();
583	if (!is_null($piwikVersion)) {
584	$dependency->setPiwikVersion($piwikVersion);
585	}
586	return $dependency;
587	}
588	/**
589	* Get all changes for this plugin
590	*
591	* @return array Array of changes
592	* [{"title":"abc","description":"xyz","linkName":"def","link":"https://link","version":"1.2.3"}]
593	*/
594	public function getChanges()
595	{
596	$file = Manager::getPluginDirectory($this->pluginName) . '/changes.json';
597	if (file_exists($file)) {
598	$json = file_get_contents($file);
599	if ($json) {
600	$changes = json_decode($json, true);
601	if ($changes && is_array($changes)) {
602	return array_reverse($changes);
603	}
604	}
605	}
606	return [];
607	}
608	}
609	}
610