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

matomo / app / core / Plugin.php

matomo / app / core Last commit date

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

Plugin.php

607 lines

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