Cleanup and phpdoc

AgID · Oct 22, 2019 · 9dae4fc · 9dae4fc
1 parent b462911
commit 9dae4fc
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 4 deletions.
diff --git a/Menu.php b/Menu.php
@@ -6,8 +6,16 @@
 use Piwik\Piwik;
 use Piwik\Plugin\Menu as MatomoMenu;
 
+/**
+ * WAI Portal menu provider.
+ */
 class Menu extends MatomoMenu
 {
+    /**
+     * Configure analytics items menu.
+     *
+     * @param MenuTop $menu the menu reference
+     */
     public function configureTopMenu(MenuTop $menu)
     {
         // Intercept menu configuration to remove unwanted icons

diff --git a/SystemSettings.php b/SystemSettings.php
@@ -9,23 +9,35 @@
 namespace Piwik\Plugins\WAIPortal;
 
 use Piwik\Piwik;
-use Piwik\Settings\Setting;
 use Piwik\Settings\FieldConfig;
+use Piwik\Settings\Plugin\SystemSettings as BaseSystemSettings;
 use Piwik\Validators\NotEmpty;
 
 /**
- * Defines Settings for WAIPortal.
+ * System Settings for WAIPortal Theme.
  */
-class SystemSettings extends \Piwik\Settings\Plugin\SystemSettings
+class SystemSettings extends BaseSystemSettings
 {
-    /** @var Setting */
+    /**
+     * WAI Portal URL setting.
+     *
+     * @var string the URL
+     */
     public $waiUrl;
 
+    /**
+     * Define system settings.
+     */
     protected function init()
     {
         $this->waiUrl = $this->createDescriptionSetting();
     }
 
+    /**
+     * Create WAI Portal URL setting.
+     *
+     * @return \Piwik\Settings\Plugin\SystemSetting the configured setting
+     */
     private function createDescriptionSetting()
     {
         $default = 'https://localhost';

diff --git a/WAIPortal.php b/WAIPortal.php
@@ -15,21 +15,51 @@
 use Piwik\Plugins\CoreAdminHome\CustomLogo;
 use Piwik\View;
 
+/**
+ * WAI Portal theme plugin.
+ */
 class WAIPortal extends Plugin
 {
+    /**
+     * The base plugin path.
+     *
+     * @var string the path
+     */
     const PLUGIN_PATH = 'plugins/WAIPortal';
 
+    /**
+     * Socials list
+     *
+     * @var mixed the list
+     */
     private $socials;
 
+    /**
+     * Footer list
+     *
+     * @var mixed the list
+     */
     private $footerLinks;
 
+    /**
+     * WAIPortal constructor.
+     * @param string|bool $pluginName A plugin name to force. If not supplied, it is set
+     *                                to the last part of the class name.
+     * @throws \Exception If plugin metadata is defined in both the getInformation() method
+     *                    and the **plugin.json** file.
+     */
     public function __construct($pluginName = false)
     {
         parent::__construct($pluginName);
         $this->socials = json_decode(@file_get_contents(self::PLUGIN_PATH . '/data/socials.json'), true);
         $this->footerLinks = json_decode(@file_get_contents(self::PLUGIN_PATH . '/data/footer_links.json'), true);
     }
 
+    /**
+     * Register observer to events.
+     *
+     * @return array the list of events with associated observer
+     */
     public function registerEvents() {
         return array(
             'Template.beforeTopBar' => 'handleAddTopBar',
@@ -39,6 +69,14 @@ public function registerEvents() {
         );
     }
 
+    /**
+     * Handle "before adding top bar" event.
+     *
+     * @param string $outstring the HTML string to modify
+     * @param string $page the current location
+     * @param string|null $userLogin the current user login
+     * @param string|null $topMenu the top menu
+     */
     public function handleAddTopBar(&$outstring, $page, $userLogin = null, $topMenu = null)
     {
         if ('login' === $page) {
@@ -48,6 +86,11 @@ public function handleAddTopBar(&$outstring, $page, $userLogin = null, $topMenu
         }
     }
 
+    /**
+     * Handle "add header" event.
+     *
+     * @param string $outstring the HTML string to modify
+     */
     public function handleTemplateHeader(&$outstring)
     {
         $view = new View('@WAIPortal/itHeader');
@@ -57,6 +100,11 @@ public function handleTemplateHeader(&$outstring)
         $outstring .= $view->render();
     }
 
+    /**
+     * Handle "add page page footer" event.
+     *
+     * @param string $outstring the HTML string to modify
+     */
     public function handleTemplatePageFooter(&$outstring)
     {
         $view = new View('@WAIPortal/itFooter');
@@ -68,6 +116,13 @@ public function handleTemplatePageFooter(&$outstring)
         $outstring .= $view->render();
     }
 
+    /**
+     * Handle "add navigation bar to login page" event.
+     *
+     * @param string $outstring the HTML string to modify
+     * @param string $position "top" to signal initial inserting before default content,
+     *                         "bottom" ti signal inserting after default content
+     */
     public function handleLoginNav(&$outstring, $position)
     {
         if ('bottom' === $position) {
@@ -79,13 +134,19 @@ public function handleLoginNav(&$outstring, $position)
         $outstring .= '<div class="hide">';
     }
 
+    /**
+     * Manage plugin activation.
+     */
     public function activate() {
         @copy(PIWIK_DOCUMENT_ROOT . '/plugins/WAIPortal/images/logo.png', PIWIK_DOCUMENT_ROOT . '/' . CustomLogo::getPathUserLogo());
         @copy(PIWIK_DOCUMENT_ROOT . '/plugins/WAIPortal/svg/logo.svg', PIWIK_DOCUMENT_ROOT . '/' . CustomLogo::getPathUserSvgLogo());
         @copy(PIWIK_DOCUMENT_ROOT . '/plugins/WAIPortal/icons/favicon-32x32.png', PIWIK_DOCUMENT_ROOT . '/' . CustomLogo::getPathUserFavicon());
         Option::set('branding_use_custom_logo', '1', true);
     }
 
+    /**
+     * Manage plugin deactivation.
+     */
     public function deactivate() {
         Filesystem::remove(PIWIK_DOCUMENT_ROOT . '/' . CustomLogo::getPathUserLogo());
         Filesystem::remove(PIWIK_DOCUMENT_ROOT . '/' .CustomLogo::getPathUserSvgLogo());