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

matomo / app / core / Plugin.php

matomo / app / core Last commit date

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

Plugin.php

600 lines

1	<?php
2	/**
3	* Piwik - free/libre analytics platform
4	*
5	* @link https://matomo.org
6	* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
7	*
8	*/
9	namespace Piwik;
10
11	use Piwik\Container\StaticContainer;
12	use Piwik\Plugin\Dependency;
13	use Piwik\Plugin\Manager;
14	use Piwik\Plugin\MetadataLoader;
15
16	if (!class_exists('Piwik\Plugin')) {
17
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	/**
100	* Holds plugin metadata.
101	*
102	* @var array
103	*/
104	private $pluginInformation;
105
106	/**
107	* As the cache is used quite often we avoid having to create instances all the time. We reuse it which is not
108	* perfect but efficient. If the cache is used we need to make sure to call setId() before usage as there
109	* is maybe a different key set since last usage.
110	*
111	* @var \Piwik\Cache\Eager
112	*/
113	private $cache;
114
115	/**
116	* Constructor.
117	*
118	* @param string\|bool $pluginName A plugin name to force. If not supplied, it is set
119	* to the last part of the class name.
120	* @throws \Exception If plugin metadata is defined in both the getInformation() method
121	* and the plugin.json file.
122	*/
123	public function __construct($pluginName = false)
124	{
125	if (empty($pluginName)) {
126	$pluginName = explode('\\', get_class($this));
127	$pluginName = end($pluginName);
128	}
129	$this->pluginName = $pluginName;
130
131	$cacheId = 'Plugin' . $pluginName . 'Metadata';
132	$cache = Cache::getEagerCache();
133
134	if ($cache->contains($cacheId)) {
135	$this->pluginInformation = $cache->fetch($cacheId);
136	} else {
137	$this->reloadPluginInformation();
138
139	$cache->save($cacheId, $this->pluginInformation);
140	}
141	}
142
143	public function reloadPluginInformation()
144	{
145	$metadataLoader = new MetadataLoader($this->pluginName);
146	$this->pluginInformation = $metadataLoader->load();
147
148	if ($this->hasDefinedPluginInformationInPluginClass() && $metadataLoader->hasPluginJson()) {
149	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);
150	}
151	}
152
153	private function createCacheIfNeeded()
154	{
155	if (is_null($this->cache)) {
156	$this->cache = Cache::getEagerCache();
157	}
158	}
159
160	private function hasDefinedPluginInformationInPluginClass()
161	{
162	$myClassName = get_class();
163	$pluginClassName = get_class($this);
164
165	if ($pluginClassName == $myClassName) {
166	// plugin has not defined its own class
167	return false;
168	}
169
170	$foo = new \ReflectionMethod(get_class($this), 'getInformation');
171	$declaringClass = $foo->getDeclaringClass()->getName();
172
173	return $declaringClass != $myClassName;
174	}
175
176	/**
177	* Returns plugin information, including:
178	*
179	* - 'description' => string // 1-2 sentence description of the plugin
180	* - 'author' => string // plugin author
181	* - 'author_homepage' => string // author homepage URL (or email "mailto:youremail@example.org")
182	* - 'homepage' => string // plugin homepage URL
183	* - 'license' => string // plugin license
184	* - '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
185	* - 'theme' => bool // Whether this plugin is a theme (a theme is a plugin, but a plugin is not necessarily a theme)
186	*
187	* @return array
188	* @deprecated
189	*/
190	public function getInformation()
191	{
192	return $this->pluginInformation;
193	}
194
195	final public function isPremiumFeature()
196	{
197	return !empty($this->pluginInformation['price']['base']);
198	}
199
200	/**
201	* Returns a list of events with associated event observers.
202	*
203	* Derived classes should use this method to associate callbacks with events.
204	*
205	* @return array eg,
206	*
207	* array(
208	* 'API.getReportMetadata' => 'myPluginFunction',
209	* 'Another.event' => array(
210	* 'function' => 'myOtherPluginFunction',
211	* 'after' => true // execute after callbacks w/o ordering
212	* )
213	* 'Yet.Another.event' => array(
214	* 'function' => 'myOtherPluginFunction',
215	* 'before' => true // execute before callbacks w/o ordering
216	* )
217	* )
218	* @since 2.15.0
219	*/
220	public function registerEvents()
221	{
222	return array();
223	}
224
225	/**
226	* @ignore
227	* @deprecated since 2.15.0 use {@link registerEvents()} instead.
228	* @return array
229	*/
230	public function getListHooksRegistered()
231	{
232	return $this->registerEvents();
233	}
234
235	/**
236	* This method is executed after a plugin is loaded and translations are registered.
237	* Useful for initialization code that uses translated strings.
238	*/
239	public function postLoad()
240	{
241	return;
242	}
243
244	/**
245	* Defines whether the whole plugin requires a working internet connection
246	* If set to true, the plugin will be automatically unloaded if `enable_internet_features` is 0,
247	* even if the plugin is activated
248	*
249	* @return bool
250	*/
251	public function requiresInternetConnection()
252	{
253	return false;
254	}
255
256	/**
257	* Installs the plugin. Derived classes should implement this class if the plugin
258	* needs to:
259	*
260	* - create tables
261	* - update existing tables
262	* - etc.
263	*
264	* @throws \Exception if installation of fails for some reason.
265	*/
266	public function install()
267	{
268	return;
269	}
270
271	/**
272	* Uninstalls the plugins. Derived classes should implement this method if the changes
273	* made in {@link install()} need to be undone during uninstallation.
274	*
275	* In most cases, if you have an {@link install()} method, you should provide
276	* an {@link uninstall()} method.
277	*
278	* @throws \Exception if uninstallation of fails for some reason.
279	*/
280	public function uninstall()
281	{
282	return;
283	}
284
285	/**
286	* Executed every time the plugin is enabled.
287	*/
288	public function activate()
289	{
290	return;
291	}
292
293	/**
294	* Executed every time the plugin is disabled.
295	*/
296	public function deactivate()
297	{
298	return;
299	}
300
301	/**
302	* Returns the plugin version number.
303	*
304	* @return string
305	*/
306	final public function getVersion()
307	{
308	$info = $this->getInformation();
309	return $info['version'];
310	}
311
312	/**
313	* Returns `true` if this plugin is a theme, `false` if otherwise.
314	*
315	* @return bool
316	*/
317	public function isTheme()
318	{
319	$info = $this->getInformation();
320	return !empty($info['theme']) && (bool)$info['theme'];
321	}
322
323	/**
324	* Returns the plugin's base class name without the namespace,
325	* e.g., `"UserCountry"` when the plugin class is `"Piwik\Plugins\UserCountry\UserCountry"`.
326	*
327	* @return string
328	*/
329	final public function getPluginName()
330	{
331	return $this->pluginName;
332	}
333
334	/**
335	* Tries to find a component such as a Menu or Tasks within this plugin.
336	*
337	* @param string $componentName The name of the component you want to look for. In case you request a
338	* component named 'Menu' it'll look for a file named 'Menu.php' within the
339	* root of the plugin folder that implements a class named
340	* Piwik\Plugin\$PluginName\Menu . If such a file exists but does not implement
341	* this class it'll silently ignored.
342	* @param string $expectedSubclass If not empty, a check will be performed whether a found file extends the
343	* given subclass. If the requested file exists but does not extend this class
344	* a warning will be shown to advice a developer to extend this certain class.
345	*
346	* @return string\|null Null if the requested component does not exist or an instance of the found
347	* component.
348	*/
349	public function findComponent($componentName, $expectedSubclass)
350	{
351	$this->createCacheIfNeeded();
352
353	$cacheId = 'Plugin' . $this->pluginName . $componentName . $expectedSubclass;
354
355	$pluginsDir = Manager::getPluginDirectory($this->pluginName);
356
357	$componentFile = sprintf('%s/%s.php', $pluginsDir, $componentName);
358
359	if ($this->cache->contains($cacheId)) {
360	$classname = $this->cache->fetch($cacheId);
361
362	if (empty($classname)) {
363	return null; // might by "false" in case has no menu, widget, ...
364	}
365
366	if (file_exists($componentFile)) {
367	include_once $componentFile;
368	}
369	} else {
370	$this->cache->save($cacheId, false); // prevent from trying to load over and over again for instance if there is no Menu for a plugin
371
372	if (!file_exists($componentFile)) {
373	return null;
374	}
375
376	require_once $componentFile;
377
378	$classname = sprintf('Piwik\\Plugins\\%s\\%s', $this->pluginName, $componentName);
379
380	if (!class_exists($classname)) {
381	return null;
382	}
383
384	if (!empty($expectedSubclass) && !is_subclass_of($classname, $expectedSubclass)) {
385	Log::warning(sprintf('Cannot use component %s for plugin %s, class %s does not extend %s',
386	$componentName, $this->pluginName, $classname, $expectedSubclass));
387	return null;
388	}
389
390	$this->cache->save($cacheId, $classname);
391	}
392
393	return $classname;
394	}
395
396	public function findMultipleComponents($directoryWithinPlugin, $expectedSubclass)
397	{
398	$this->createCacheIfNeeded();
399
400	$cacheId = 'Plugin' . $this->pluginName . $directoryWithinPlugin . $expectedSubclass;
401
402	if ($this->cache->contains($cacheId)) {
403	$components = $this->cache->fetch($cacheId);
404
405	if ($this->includeComponents($components)) {
406	return $components;
407	} else {
408	// problem including one cached file, refresh cache
409	}
410	}
411
412	$components = $this->doFindMultipleComponents($directoryWithinPlugin, $expectedSubclass);
413
414	$this->cache->save($cacheId, $components);
415
416	return $components;
417	}
418
419	/**
420	* Detect whether there are any missing dependencies.
421	*
422	* @param null $piwikVersion Defaults to the current Piwik version
423	* @return bool
424	*/
425	public function hasMissingDependencies($piwikVersion = null)
426	{
427	$requirements = $this->getMissingDependencies($piwikVersion);
428
429	return !empty($requirements);
430	}
431
432	public function getMissingDependencies($piwikVersion = null)
433	{
434	if (empty($this->pluginInformation['require'])) {
435	return array();
436	}
437
438	$dependency = $this->makeDependency($piwikVersion);
439	return $dependency->getMissingDependencies($this->pluginInformation['require']);
440	}
441
442	/**
443	* Returns a string (translated) describing the missing requirements for this plugin and the given Piwik version
444	*
445	* @param string $piwikVersion
446	* @return string "AnonymousPiwikUsageMeasurement requires PIWIK >=3.0.0"
447	*/
448	public function getMissingDependenciesAsString($piwikVersion = null)
449	{
450	if ($this->requiresInternetConnection() && !SettingsPiwik::isInternetEnabled()) {
451	return Piwik::translate('CorePluginsAdmin_PluginRequiresInternet');
452	}
453
454	if (empty($this->pluginInformation['require'])) {
455	return '';
456	}
457	$dependency = $this->makeDependency($piwikVersion);
458
459	$missingDependencies = $dependency->getMissingDependencies($this->pluginInformation['require']);
460
461	if(empty($missingDependencies)) {
462	return '';
463	}
464
465	$causedBy = array();
466	foreach ($missingDependencies as $dependency) {
467	$causedBy[] = ucfirst($dependency['requirement']) . ' ' . $dependency['causedBy'];
468	}
469
470	return Piwik::translate("CorePluginsAdmin_PluginRequirement", array(
471	$this->getPluginName(),
472	implode(', ', $causedBy)
473	));
474	}
475
476
477	/**
478	* Extracts the plugin name from a backtrace array. Returns `false` if we can't find one.
479	*
480	* @param array $backtrace The result of {@link debug_backtrace()} or
481	* [Exception::getTrace()](http://www.php.net/manual/en/exception.gettrace.php).
482	* @return string\|false
483	*/
484	public static function getPluginNameFromBacktrace($backtrace)
485	{
486	foreach ($backtrace as $tracepoint) {
487	// try and discern the plugin name
488	if (isset($tracepoint['class'])) {
489	$className = self::getPluginNameFromNamespace($tracepoint['class']);
490	if ($className) {
491	return $className;
492	}
493	}
494	}
495	return false;
496	}
497
498	/**
499	* Extracts the plugin name from a namespace name or a fully qualified class name. Returns `false`
500	* if we can't find one.
501	*
502	* @param string $namespaceOrClassName The namespace or class string.
503	* @return string\|false
504	*/
505	public static function getPluginNameFromNamespace($namespaceOrClassName)
506	{
507	if (preg_match("/Piwik\\\\Plugins\\\\([a-zA-Z_0-9]+)\\\\/", $namespaceOrClassName, $matches)) {
508	return $matches[1];
509	} else {
510	return false;
511	}
512	}
513
514	/**
515	* Override this method in your plugin class if you want your plugin to be loaded during tracking.
516	*
517	* Note: If you define your own dimension or handle a tracker event, your plugin will automatically
518	* be detected as a tracker plugin.
519	*
520	* @return bool
521	* @internal
522	*/
523	public function isTrackerPlugin()
524	{
525	return false;
526	}
527
528	/**
529	* @param $directoryWithinPlugin
530	* @param $expectedSubclass
531	* @return array
532	*/
533	private function doFindMultipleComponents($directoryWithinPlugin, $expectedSubclass)
534	{
535	$components = array();
536
537	$pluginsDir = Manager::getPluginDirectory($this->pluginName);
538	$baseDir = $pluginsDir . '/' . $directoryWithinPlugin;
539
540	$files = Filesystem::globr($baseDir, '*.php');
541
542	foreach ($files as $file) {
543	require_once $file;
544
545	$fileName = str_replace(array($baseDir . '/', '.php'), '', $file);
546	$klassName = sprintf('Piwik\\Plugins\\%s\\%s\\%s', $this->pluginName, str_replace('/', '\\', $directoryWithinPlugin), str_replace('/', '\\', $fileName));
547
548	if (!class_exists($klassName)) {
549	continue;
550	}
551
552	if (!empty($expectedSubclass) && !is_subclass_of($klassName, $expectedSubclass)) {
553	continue;
554	}
555
556	$klass = new \ReflectionClass($klassName);
557
558	if ($klass->isAbstract()) {
559	continue;
560	}
561
562	$components[$file] = $klassName;
563	}
564	return $components;
565	}
566
567	/**
568	* @param $components
569	* @return bool true if all files were included, false if any file cannot be read
570	*/
571	private function includeComponents($components)
572	{
573	foreach ($components as $file => $klass) {
574	if (!is_readable($file)) {
575	return false;
576	}
577	}
578	foreach ($components as $file => $klass) {
579	include_once $file;
580	}
581	return true;
582	}
583
584	/**
585	* @param $piwikVersion
586	* @return Dependency
587	*/
588	private function makeDependency($piwikVersion)
589	{
590	$dependency = new Dependency();
591
592	if (!is_null($piwikVersion)) {
593	$dependency->setPiwikVersion($piwikVersion);
594	}
595	return $dependency;
596	}
597	}
598	}
599
600