Code style fixes: License header, phpdoc tags, psr-2 compliance

refs #4530

application/controllers/ConfigController.php

@@ -1,6 +1,5 @@
 <?php
 // @codingStandardsIgnoreStart
-
 // {{{ICINGA_LICENSE_HEADER}}}
 /**
  * Icinga 2 Web - Head for multiple monitoring frontends
@@ -33,12 +32,18 @@ use Icinga\Web\Url;
 use Icinga\Web\Hook\Configuration\ConfigurationTabBuilder;
 use Icinga\Application\Icinga;
 
-
 /**
- * Class ConfigController
+ * Application wide controller for application preferences
+ *
  */
 class ConfigController extends BaseConfigController
 {
+    /**
+     * Create tabs for this configuration controller
+     *
+     * @return array
+     * @see BaseConfigController::createProvidedTabs
+     */
     public static function createProvidedTabs()
     {
         return array(
@@ -63,13 +68,17 @@ class ConfigController extends BaseConfigController
     }
 
     /**
-     * Index action
+     * Index action, entry point for configuration
+     * @TODO: Implement configuration interface (#3777)
      */
     public function indexAction()
     {
 
     }
 
+    /**
+     * Display the list of all modules
+     */
     public function moduleoverviewAction()
     {
         $this->view->modules = Icinga::app()->getModuleManager()->select()
@@ -79,7 +88,7 @@ class ConfigController extends BaseConfigController
     }
 
     /**
-     * Enable a module
+     * Enable a specific module provided by the 'name' param
      */
     public function moduleenableAction()
     {
@@ -91,7 +100,7 @@ class ConfigController extends BaseConfigController
     }
 
     /**
-     * Disable a module
+     * Disable a module specific module provided by the 'name' param
      */
     public function moduledisableAction()
     {
@@ -100,5 +109,4 @@ class ConfigController extends BaseConfigController
         $this->redirectNow('config/moduleoverview?_render=body');
     }
 }
-
+// @codingStandardsIgnoreEnd
-// @codingStandardsIgnoreEnd

application/controllers/PreferenceController.php

@@ -1,4 +1,5 @@
 <?php
+// @codingStandardsIgnoreStart
 // {{{ICINGA_LICENSE_HEADER}}}
 /**
  * This file is part of Icinga 2 Web.
@@ -38,9 +39,10 @@ class PreferenceController extends BasePreferenceController
 {
 
     /**
-     *  @see BasePreferenceController::createProvidedTabs
+     * Create tabs for this preference controller
      *
      *  @return array
+     *  @see    BasePreferenceController::createProvidedTabs
      */
     public static function createProvidedTabs()
     {
@@ -64,4 +66,5 @@ class PreferenceController extends BasePreferenceController
     {
 
     }
-}
+}
+// @codingStandardsIgnoreEnd

library/Icinga/Application/Modules/Manager.php

@@ -1,7 +1,10 @@
 <?php
+// {{{ICINGA_LICENSE_HEADER}}}
+// {{{ICINGA_LICENSE_HEADER}}}
 
 namespace Icinga\Application\Modules;
 
+use Icinga\Application\ApplicationBootstrap;
 use Icinga\Application\Icinga;
 use Icinga\Exception\ConfigurationError;
 use Icinga\Exception\SystemPermissionException;
@@ -25,50 +28,53 @@ class Manager
      *
      * @var array|null
      */
-    protected $installedBaseDirs = null;
+    private $installedBaseDirs = null;
 
     /**
      * Array of all enabled modules base dirs
      *
      * @var array
      */
-    protected $enabledDirs       = array();
+    private $enabledDirs       = array();
 
     /**
      * Array of all module names that have been loaded
      *
      * @var array
      */
-    protected $loadedModules     = array();
+    private $loadedModules     = array();
 
     /**
      * Reference to Icinga::app
      *
      * @var Icinga
      */
-    protected $app;
+    private $app;
 
     /**
      * The directory that is used to detect enabled modules
      *
      * @var string
      */
-    protected $enableDir;
+    private $enableDir;
 
     /**
      * All paths to look for installed modules that can be enabled
      *
      * @var array
      */
-    protected $modulePaths = array();
+    private $modulePaths = array();
 
     /**
-     * Creates a new instance of the module manager to
+     *  Create a new instance of the module manager
      *
-     *  @param $app :   The applicaiton bootstrap. This one needs a properly defined interface
+     *  @param ApplicationBootstrap $app    The application bootstrap. This one needs a properly defined interface
-    *                   In order to test it correctly, the application now only requires a stdClass
+     *                                      In order to test it correctly, the application now only requires a stdClass
-    *   @param $dir :   
+     *  @param string $enabledDir           The path of the dir used for adding symlinks to enabled modules
-    **/
+     *                                      ( must be writable )
+     *  @param array $availableDirs         An array containing all paths where the modulemanager can look for available
+     *                                      modules
+     **/
     public function __construct($app, $enabledDir = null, array $availableDirs = array())
     {
         $this->app = $app;
@@ -84,7 +90,13 @@ class Manager
         $this->detectEnabledModules();
     }
 
-    protected function prepareEssentials($moduleDir)
+    /**
+     * Set the module dir and checks for existence
+     *
+     * @param string $moduleDir                     The module directory to set for the module manager
+     * @throws \Icinga\Exception\ProgrammingError
+     */
+    private function prepareEssentials($moduleDir)
     {
         $this->enableDir = $moduleDir;
 
@@ -98,13 +110,22 @@ class Manager
         }
     }
 
+    /**
+     * Query interface for the module manager
+     *
+     * @return \Icinga\Data\ArrayQuery
+     */
     public function select()
     {
         $source = new \Icinga\Data\ArrayDatasource($this->getModuleInfo());
         return $source->select();
     }
 
-    protected function detectEnabledModules()
+    /**
+     *  Check for enabled modules and update the internal $enabledDirs property with the enabled modules
+     *
+     */
+    private function detectEnabledModules()
     {
         $fh = opendir($this->enableDir);
 
@@ -117,11 +138,22 @@ class Manager
 
             $link = $this->enableDir . '/' . $file;
             if (! is_link($link)) {
+                Logger::warn(
+                    'Found invalid module in enabledModule directory "%s": "%s" is not a symlink',
+                    $this->enableDir,
+                    $link
+                );
                 continue;
             }
 
             $dir = realpath($link);
             if (! file_exists($dir) || ! is_dir($dir)) {
+                Logger::warn(
+                    'Found invalid module in enabledModule directory "%s": "%s" points to non existing path "%s"',
+                    $this->enableDir,
+                    $link,
+                    $dir
+                );
                 continue;
             }
 
@@ -129,6 +161,12 @@ class Manager
         }
     }
 
+    /**
+     * Try to set all enabled modules in loaded sate
+     *
+     * @return  self
+     * @see     Manager::loadModule()
+     */
     public function loadEnabledModules()
     {
         foreach ($this->listEnabledModules() as $name) {
@@ -137,6 +175,14 @@ class Manager
         return $this;
     }
 
+    /**
+     * Try to load the module and register it in the application
+     *
+     * @param string $name              The name of the module to load
+     * @param null|mixed $moduleBase    An alternative class to use instead of @see Module, used for testing
+     *
+     * @return self
+     */
     public function loadModule($name, $moduleBase = null)
     {
         if ($this->hasLoaded($name)) {
@@ -154,6 +200,15 @@ class Manager
         return $this;
     }
 
+    /**
+     * Set the given module to the enabled state
+     *
+     * @param string $name                                  The module to enable
+     *
+     * @return self
+     * @throws \Icinga\Exception\ConfigurationError         When trying to enable a module that is not installed
+     * @throws \Icinga\Exception\SystemPermissionException  When insufficient permissions for the application exist
+     */
     public function enableModule($name)
     {
         if (! $this->hasInstalled($name)) {
@@ -188,6 +243,15 @@ class Manager
         return $this;
     }
 
+    /**
+     * Disable the given module and remove it's enabled state
+     *
+     * @param string $name                                  The name of the module to disable
+     *
+     * @return self
+     * @throws \Icinga\Exception\ConfigurationError         When the module is not installed or it's not symlinked
+     * @throws \Icinga\Exception\SystemPermissionException  When the module can't be disabled
+     */
     public function disableModule($name)
     {
         if (! $this->hasEnabled($name)) {
@@ -222,11 +286,15 @@ class Manager
         return $this;
     }
 
-    public function getModuleConfigDir($name)
+    /**
-    {
+     * Return the directory of the given module as a string, optionally with a given sub directoy
-        return $this->getModuleDir($name, '/config');
+     *
-    }
+     * @param string $name                          The module name to return the module directory of
-
+     * @param string $subdir                        The sub directory to append to the path
+     *
+     * @return string
+     * @throws \Icinga\Exception\ProgrammingError   When the module is not installed or existing
+     */
     public function getModuleDir($name, $subdir = '')
     {
         if ($this->hasEnabled($name)) {
@@ -245,6 +313,12 @@ class Manager
         );
     }
 
+    /**
+     * Return true when the module with the given name is installed, otherwise false
+     *
+     * @param string $name          The module to check for being installed
+     * @return bool
+     */
     public function hasInstalled($name)
     {
         if ($this->installedBaseDirs === null) {
@@ -253,21 +327,49 @@ class Manager
         return array_key_exists($name, $this->installedBaseDirs);
     }
 
+    /**
+     * Return true when the given module is in enabled state, otherwise false
+     *
+     * @param string $name          The module to check for being enabled
+     *
+     * @return bool
+     */
     public function hasEnabled($name)
     {
         return array_key_exists($name, $this->enabledDirs);
     }
 
+    /**
+     * Return true when the module is in loaded state, otherwise false
+     *
+     * @param string $name          The module to check for being loaded
+     *
+     * @return bool
+     */
     public function hasLoaded($name)
     {
         return array_key_exists($name, $this->loadedModules);
     }
 
+    /**
+     * Return an array containing all loaded modules
+     *
+     * @return  array
+     * @see     Module
+     */
     public function getLoadedModules()
     {
         return $this->loadedModules;
     }
 
+    /**
+     * Return the module instance of the given module when it is loaded
+     *
+     * @param string $name                          The module name to return
+     * @return Module
+     *
+     * @throws \Icinga\Exception\ProgrammingError   Thrown when the module hasn't been loaded
+     */
     public function getModule($name)
     {
         if (! $this->hasLoaded($name)) {
@@ -281,6 +383,17 @@ class Manager
         return $this->loadedModules[$name];
     }
 
+    /**
+     * Return an array containing information objects for each available module
+     *
+     * Each entry has the following fields
+     *  - name:     The name of the module as a string
+     *  - path:     The path where the module is located as a string
+     *  - enabled:  Whether the module is enabled or not as a boolean
+     *  - loaded:   Whether the module is loaded or not as a boolean
+     *
+     * @return array
+     */
     public function getModuleInfo()
     {
         $installed = $this->listInstalledModules();
@@ -301,16 +414,34 @@ class Manager
         return $info;
     }
 
+    /**
+     * Return an array containing all enabled module names as strings
+     *
+     * @return array
+     */
     public function listEnabledModules()
     {
         return array_keys($this->enabledDirs);
     }
 
+    /**
+     * Return an array containing all loaded module names as strings
+     *
+     * @return array
+     */
     public function listLoadedModules()
     {
         return array_keys($this->loadedModules);
     }
 
+    /**
+     * Return an array containing all installled module names as strings
+     *
+     * Calls @see Manager::detectInstalledModules if no module discovery has
+     * been performed yet
+     *
+     * @return array
+     */
     public function listInstalledModules()
     {
         if ($this->installedBaseDirs === null) {
@@ -322,6 +453,11 @@ class Manager
         }
     }
 
+    /**
+     * Detect installed modules from every path provided in modulePaths
+     *
+     * @return self
+     */
     public function detectInstalledModules()
     {
         foreach ($this->modulePaths as $basedir) {
@@ -339,6 +475,6 @@ class Manager
                 }
             }
         }
+        return $this;
     }
-
 }

library/Icinga/Application/Modules/Module.php

@@ -383,5 +383,4 @@ class Module
         Hook::register($name, $key, $class);
         return $this;
     }
-
 }

library/Icinga/Web/Controller/ActionController.php

@@ -223,12 +223,14 @@ class ActionController extends ZfController
         // TODO(el): What is this, why do we need that here?
         $this->view->compact = $this->_request->getParam('view') === 'compact';
 
-        Benchmark::measure(sprintf(
+        Benchmark::measure(
-            'Action::preDispatched(): %s / %s / %s',
+            sprintf(
-            $this->module_name,
+                'Action::preDispatched(): %s / %s / %s',
-            $this->controller_name,
+                $this->module_name,
-            $this->action_name
+                $this->controller_name,
-        ));
+                $this->action_name
+            )
+        );
 
         //$this->quickRedirect('/authentication/login?a=e');
     }
@@ -281,26 +283,10 @@ class ActionController extends ZfController
             require_once 'vendor/lessphp/lessc.inc.php';
             $less = new \lessc;
             $cssdir = dirname(ICINGA_LIBDIR) . '/public/css';
-             // TODO: We need a way to retrieve public dir, even if located elsewhere
+            // TODO: We need a way to retrieve public dir, even if located elsewhere
 
             $css = $less->compileFile($cssdir . '/pdfprint.less');
-/*
+            $this->render(
-            foreach (\Icinga\Application\Icinga::app()->getModuleManager()->getLoadedModules() as $name => $module) {
-                if ($module->hasCss()) {
-                    $css .= $less->compile(
-                        '.icinga-module.module-'
-                        . $name
-                        . " {\n"
-                        . file_get_contents($module->getCssFilename())
-                        . "}\n\n"
-                    );
-                }
-            }
-
-*/
-            // END of CSS test
-
-             $this->render(
                 null,
                 $this->_helper->viewRenderer->getResponseSegment(),
                 $this->_helper->viewRenderer->getNoController()
@@ -308,18 +294,15 @@ class ActionController extends ZfController
             $html = (string) $this->getResponse();
             if ($this->module_name !== null) {
                 $html = '<div class="icinga-module module-'
-          . $this->module_name
+                . $this->module_name
-          . '">'
+                . '">'
-          . "\n"
+                . "\n"
-          . $html
+                . $html
-          . '</div>';
+                . '</div>';
             }
 
             $html = '<style>' . $css . '</style>' . $html;
 
-            //$html .= $this->view->action('services', 'list', 'monitoring', array('limit' => 10));
-//            $html = preg_replace('~icinga-module.module-bpapp~', 'csstest', $html);
-// echo $html; exit;
             $pdf = new Pdf();
             $pdf->AddPage();
             $pdf->setFontSubsetting(false);
@@ -356,6 +339,5 @@ class ActionController extends ZfController
             Benchmark::measure('Response ready');
             $this->_helper->layout()->benchmark = $this->renderBenchmark();
         }
-
     }
 }

library/Icinga/Web/Controller/BaseConfigController.php

@@ -26,7 +26,6 @@
  */
 // {{{ICINGA_LICENSE_HEADER}}}
 
-
 namespace Icinga\Web\Controller;
 
 use \Icinga\Application\Icinga;
@@ -55,6 +54,8 @@ class BaseConfigController extends ActionController
     }
 
     /**
+     * Initialize the controller and collect all tabs for it from the application and it's modules
+     *
      * @see ActionController::init
      */
     public function init()

library/Icinga/Web/Controller/BasePreferenceController.php

@@ -52,6 +52,8 @@ class BasePreferenceController extends ActionController
     }
 
     /**
+     *  Initialize the controller and collect all tabs for it from the application and it's modules
+     *
      *  @see ActionController::init()
      */
     public function init()

modules/monitoring/application/controllers/CommandController.php

@@ -1,6 +1,5 @@
 <?php
 // @codingStandardsIgnoreStart
-
 // {{{ICINGA_LICENSE_HEADER}}}
 /**
  * This file is part of Icinga 2 Web.

modules/monitoring/application/controllers/ConfigController.php

@@ -1,4 +1,5 @@
 <?php
+// @codingStandardsIgnoreStart
 // {{{ICINGA_LICENSE_HEADER}}}
 /**
  * This file is part of Icinga 2 Web.
@@ -49,4 +50,5 @@ class Monitoring_ConfigController extends BaseConfigController {
         $this->redirectNow("/config");
     }
 
-}
+}
+// @codingStandardsIgnoreEnd

modules/monitoring/application/controllers/ListController.php

@@ -1,5 +1,31 @@
 <?php
-
+// @codingStandardsIgnoreStart
+// {{{ICINGA_LICENSE_HEADER}}}
+/**
+ * This file is part of Icinga 2 Web.
+ *
+ * Icinga 2 Web - Head for multiple monitoring backends.
+ * Copyright (C) 2013 Icinga Development Team
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * @copyright 2013 Icinga Development Team <info@icinga.org>
+ * @license   http://www.gnu.org/licenses/gpl-2.0.txt GPL, version 2
+ * @author    Icinga Development Team <info@icinga.org>
+ */
+// {{{ICINGA_LICENSE_HEADER}}}
 use Icinga\Web\Controller\ModuleActionController;
 use Icinga\Web\Hook;
 use Icinga\File\Csv;
@@ -9,9 +35,26 @@ use Icinga\Web\Widget\Tabs;
 
 class Monitoring_ListController extends ModuleActionController
 {
+    /**
+     * The backend used for this controller
+     *
+     * @var \Icinga\Backend
+     */
     protected $backend;
+
+    /**
+     * Set to a string containing the compact layout name to use when
+     * 'compact' is set as the layout parameter, otherwise null
+     *
+     * @var string|null
+     */
     private $compactView = null;
 
+    /**
+     * Retrieve backend and hooks for this controller
+     *
+     * @see ActionController::init
+     */
     public function init()
     {
         $this->view->tabs = $this->getTabs()
@@ -21,6 +64,9 @@ class Monitoring_ListController extends ModuleActionController
         $this->view->grapher = Hook::get('grapher');
     }
 
+    /**
+     * Display host list
+     */
     public function hostsAction()
     {
         Benchmark::measure("hostsAction::query()");
@@ -50,6 +96,9 @@ class Monitoring_ListController extends ModuleActionController
         );
     }
 
+    /**
+     * Display service list
+     */
     public function servicesAction()
     {
         $state_type = $this->_getParam('_statetype', 'soft');
@@ -93,6 +142,11 @@ class Monitoring_ListController extends ModuleActionController
         $this->inheritCurrentSortColumn();
     }
 
+    /**
+     * Display hostgroup list
+     *
+     * @TODO Implement hostgroup overview (feature #4184)
+     */
     public function hostgroupsAction()
     {
         $this->view->hostgroups = $this->backend->select()
@@ -102,6 +156,11 @@ class Monitoring_ListController extends ModuleActionController
         ))->applyRequest($this->_request);
     }
 
+    /**
+     * Display servicegroup list
+     *
+     * @TODO Implement servicegroup overview (feature #4185)
+     */
     public function servicegroupsAction()
     {
         $this->view->servicegroups = $this->backend->select()
@@ -111,6 +170,11 @@ class Monitoring_ListController extends ModuleActionController
         ))->applyRequest($this->_request);
     }
 
+    /**
+     * Display contactgroups overview
+     *
+     *
+     */
     public function contactgroupsAction()
     {
         $this->view->contactgroups = $this->backend->select()
@@ -120,33 +184,6 @@ class Monitoring_ListController extends ModuleActionController
         ))->applyRequest($this->_request);
     }
 
-    public function contactsAction()
-    {
-        $this->view->contacts = $this->backend->select()
-            ->from('contact', array(
-            'contact_name',
-            'contact_alias',
-            'contact_email',
-            'contact_pager'
-        ))->applyRequest($this->_request);
-    }
-
-    // TODO: Search helper playground
-    public function searchAction()
-    {
-        $data = array(
-            'service_description',
-            'service_state',
-            'service_acknowledged',
-            'service_handled',
-            'service_output',
-            // '_host_satellite',
-            'service_last_state_change'
-            );
-        echo json_encode($data);
-        exit;
-    }
-
     /**
      * Fetch the current downtimes and put them into the view
      * property 'downtimes'
@@ -177,6 +214,14 @@ class Monitoring_ListController extends ModuleActionController
         $this->inheritCurrentSortColumn();
     }
 
+    /**
+     * Create a query for the given view
+     *
+     * @param string $view              An string identifying view to query
+     * @param array $columns            An array with the column names to display
+     *
+     * @return \Icinga\Data\Db\Query
+     */
     protected function query($view, $columns)
     {
         $extra = preg_split(
@@ -194,6 +239,11 @@ class Monitoring_ListController extends ModuleActionController
         return $query;
     }
 
+    /**
+     * Handle the 'format' and 'view' parameter
+     *
+     * @param \Icinga\Data\Db\Query $query      The current query
+     */
     protected function handleFormatRequest($query)
     {
         if ($this->compactView !== null && ($this->_getParam('view', false) === 'compact')) {
@@ -220,6 +270,11 @@ class Monitoring_ListController extends ModuleActionController
         }
     }
 
+    /**
+     * Return all tabs for this controller
+     *
+     * @return Tabs
+     */
     protected function getTabs()
     {
         $tabs = new Tabs();
@@ -275,3 +330,4 @@ class Monitoring_ListController extends ModuleActionController
         }
     }
 }
+// @codingStandardsIgnoreEnd

modules/monitoring/application/controllers/SummaryController.php

@@ -1,5 +1,31 @@
 <?php
-
+// @codingStandardsIgnoreStart
+// {{{ICINGA_LICENSE_HEADER}}}
+/**
+ * This file is part of Icinga 2 Web.
+ *
+ * Icinga 2 Web - Head for multiple monitoring backends.
+ * Copyright (C) 2013 Icinga Development Team
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * @copyright 2013 Icinga Development Team <info@icinga.org>
+ * @license   http://www.gnu.org/licenses/gpl-2.0.txt GPL, version 2
+ * @author    Icinga Development Team <info@icinga.org>
+ */
+// {{{ICINGA_LICENSE_HEADER}}}
 use Icinga\Web\Controller\ModuleActionController;
 use Icinga\Backend;
 use Icinga\Web\Widget\Tabs;
@@ -68,3 +94,4 @@ class Monitoring_SummaryController extends ModuleActionController
     }
 
 }
+// @codingStandardsIgnoreEnd