CS: Fix docstrings in Icinga/Application/Modules/Module.php and Manager.php

refs #4530
This commit is contained in:
Eric Lippmann 2013-08-14 16:07:17 +02:00
parent d604b01349
commit 6d98b923ca
3 changed files with 102 additions and 79 deletions

View File

@ -15,9 +15,9 @@ use \Icinga\Exception\ProgrammingError;
* Module manager that handles detecting, enabling and disabling of modules * Module manager that handles detecting, enabling and disabling of modules
* *
* Modules can have 3 states: * Modules can have 3 states:
* - installed Means that the module exists, but could be deactivated (see enabled and loaded) * * installed, module exists but is disabled
* - enabled Means that the module is marked as being enabled and should be used * * enabled, module enabled and should be loaded
* - loaded Means that the module has been registered in the autoloader and is being used * * loaded, module enabled and loaded via the autoloader
* *
*/ */
class Manager class Manager
@ -64,17 +64,15 @@ class Manager
* *
* @var array * @var array
*/ */
private $modulePaths = array(); private $modulePaths = array();
/** /**
* Create a new instance of the module manager * Create a new instance of the module manager
* *
* @param ApplicationBootstrap $app The application bootstrap. This one needs a properly defined interface * @param ApplicationBootstrap $app
* In order to test it correctly, the application now only requires a stdClass * @param string $enabledDir Enabled modules location. The application maintains symlinks within
* @param string $enabledDir The path of the dir used for adding symlinks to enabled modules * the given path
* ( must be writable ) * @param array $availableDirs Installed modules location
* @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()) public function __construct($app, $enabledDir = null, array $availableDirs = array())
{ {
@ -94,14 +92,14 @@ class Manager
/** /**
* Set the module dir and checks for existence * Set the module dir and checks for existence
* *
* @param string $moduleDir The module directory to set for the module manager * @param string $moduleDir The module directory to set for the module manager
* @throws \Icinga\Exception\ProgrammingError * @throws \Icinga\Exception\ProgrammingError
*/ */
private function prepareEssentials($moduleDir) private function prepareEssentials($moduleDir)
{ {
$this->enableDir = $moduleDir; $this->enableDir = $moduleDir;
if (! file_exists($this->enableDir) || ! is_dir($this->enableDir)) { if (!file_exists($this->enableDir) || !is_dir($this->enableDir)) {
throw new ProgrammingError( throw new ProgrammingError(
sprintf( sprintf(
'Missing module directory: %s', 'Missing module directory: %s',
@ -123,8 +121,7 @@ class Manager
} }
/** /**
* Check for enabled modules and update the internal $enabledDirs property with the enabled modules * Check for enabled modules and update the internal $enabledDirs property with the enabled modules
*
*/ */
private function detectEnabledModules() private function detectEnabledModules()
{ {
@ -138,7 +135,7 @@ class Manager
} }
$link = $this->enableDir . '/' . $file; $link = $this->enableDir . '/' . $file;
if (! is_link($link)) { if (!is_link($link)) {
Logger::warn( Logger::warn(
'Found invalid module in enabledModule directory "%s": "%s" is not a symlink', 'Found invalid module in enabledModule directory "%s": "%s" is not a symlink',
$this->enableDir, $this->enableDir,
@ -148,7 +145,7 @@ class Manager
} }
$dir = realpath($link); $dir = realpath($link);
if (! file_exists($dir) || ! is_dir($dir)) { if (!file_exists($dir) || !is_dir($dir)) {
Logger::warn( Logger::warn(
'Found invalid module in enabledModule directory "%s": "%s" points to non existing path "%s"', 'Found invalid module in enabledModule directory "%s": "%s" points to non existing path "%s"',
$this->enableDir, $this->enableDir,
@ -179,10 +176,11 @@ class Manager
/** /**
* Try to load the module and register it in the application * Try to load the module and register it in the application
* *
* @param string $name The name of the module to load * @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 * @param mixed $moduleBase Alternative class to use instead of \Icinga\Application\Modules\Module for
* instantiating modules, used for testing
* *
* @return self * @return self
*/ */
public function loadModule($name, $moduleBase = null) public function loadModule($name, $moduleBase = null)
{ {
@ -204,15 +202,15 @@ class Manager
/** /**
* Set the given module to the enabled state * Set the given module to the enabled state
* *
* @param string $name The module to enable * @param string $name The module to enable
* *
* @return self * @return self
* @throws \Icinga\Exception\ConfigurationError When trying to enable a module that is not installed * @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 * @throws \Icinga\Exception\SystemPermissionException When insufficient permissions for the application exist
*/ */
public function enableModule($name) public function enableModule($name)
{ {
if (! $this->hasInstalled($name)) { if (!$this->hasInstalled($name)) {
throw new ConfigurationError( throw new ConfigurationError(
sprintf( sprintf(
"Cannot enable module '%s' as it isn't installed", "Cannot enable module '%s' as it isn't installed",
@ -224,7 +222,7 @@ class Manager
clearstatcache(true); clearstatcache(true);
$target = $this->installedBaseDirs[$name]; $target = $this->installedBaseDirs[$name];
$link = $this->enableDir . '/' . $name; $link = $this->enableDir . '/' . $name;
if (! is_writable($this->enableDir)) { if (!is_writable($this->enableDir)) {
throw new SystemPermissionException( throw new SystemPermissionException(
"Insufficient system permissions for enabling modules", "Insufficient system permissions for enabling modules",
"write", "write",
@ -247,38 +245,39 @@ class Manager
/** /**
* Disable the given module and remove it's enabled state * Disable the given module and remove it's enabled state
* *
* @param string $name The name of the module to disable * @param string $name The name of the module to disable
* *
* @return self * @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 * @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) public function disableModule($name)
{ {
if (! $this->hasEnabled($name)) { if (!$this->hasEnabled($name)) {
return $this; return $this;
} }
if (! is_writable($this->enableDir)) { if (!is_writable($this->enableDir)) {
throw new SystemPermissionException("Can't write the module directory", "write", $this->enableDir); throw new SystemPermissionException("Can't write the module directory", "write", $this->enableDir);
return $this; return $this;
} }
$link = $this->enableDir . '/' . $name; $link = $this->enableDir . '/' . $name;
if (!file_exists($link)) { if (!file_exists($link)) {
throw new ConfigurationError("The module $name could not be found, can't disable it"); throw new ConfigurationError('The module ' . $name . ' could not be found, can\'t disable it');
} }
if (!is_link($link)) { if (!is_link($link)) {
throw new ConfigurationError( throw new ConfigurationError(
"The module $name can't be disabled as this would delete the whole module. ". 'The module ' . $name . ' can\'t be disabled as this would delete the whole module. '
"It looks like you have installed this module manually and moved it to your module folder.". . 'It looks like you have installed this module manually and moved it to your module folder. '
"In order to dynamically enable and disable modules, you have to create a symlink to ". . 'In order to dynamically enable and disable modules, you have to create a symlink to '
"the enabled_modules folder" . 'the enabled_modules folder'
); );
} }
if (file_exists($link) && is_link($link)) { if (file_exists($link) && is_link($link)) {
if (!@unlink($link)) { if (!@unlink($link)) {
$error = error_get_last(); $error = error_get_last();
throw new SystemPermissionException($error["message"], "unlink", $link); throw new SystemPermissionException($error['message'], 'unlink', $link);
} }
} else { } else {
@ -290,11 +289,12 @@ class Manager
/** /**
* Return the directory of the given module as a string, optionally with a given sub directoy * Return the directory of the given module as a string, optionally with a given sub directoy
* *
* @param string $name The module name to return the module directory of * @param string $name The module name to return the module directory of
* @param string $subdir The sub directory to append to the path * @param string $subdir The sub directory to append to the path
* *
* @return string * @return string
* @throws \Icinga\Exception\ProgrammingError When the module is not installed or existing *
* @throws \Icinga\Exception\ProgrammingError When the module is not installed or existing
*/ */
public function getModuleDir($name, $subdir = '') public function getModuleDir($name, $subdir = '')
{ {
@ -317,8 +317,9 @@ class Manager
/** /**
* Return true when the module with the given name is installed, otherwise false * Return true when the module with the given name is installed, otherwise false
* *
* @param string $name The module to check for being installed * @param string $name The module to check for being installed
* @return bool *
* @return bool
*/ */
public function hasInstalled($name) public function hasInstalled($name)
{ {
@ -331,9 +332,9 @@ class Manager
/** /**
* Return true when the given module is in enabled state, otherwise false * Return true when the given module is in enabled state, otherwise false
* *
* @param string $name The module to check for being enabled * @param string $name The module to check for being enabled
* *
* @return bool * @return bool
*/ */
public function hasEnabled($name) public function hasEnabled($name)
{ {
@ -343,9 +344,9 @@ class Manager
/** /**
* Return true when the module is in loaded state, otherwise false * Return true when the module is in loaded state, otherwise false
* *
* @param string $name The module to check for being loaded * @param string $name The module to check for being loaded
* *
* @return bool * @return bool
*/ */
public function hasLoaded($name) public function hasLoaded($name)
{ {
@ -356,7 +357,8 @@ class Manager
* Return an array containing all loaded modules * Return an array containing all loaded modules
* *
* @return array * @return array
* @see Module *
* @see \Icinga\Application\Modules\Module
*/ */
public function getLoadedModules() public function getLoadedModules()
{ {
@ -366,14 +368,15 @@ class Manager
/** /**
* Return the module instance of the given module when it is loaded * Return the module instance of the given module when it is loaded
* *
* @param string $name The module name to return * @param string $name The module name to return
* @return Module
* *
* @throws \Icinga\Exception\ProgrammingError Thrown when the module hasn't been loaded * @return \Icinga\Application\Modules\Module
*
* @throws \Icinga\Exception\ProgrammingError When the module hasn't been loaded
*/ */
public function getModule($name) public function getModule($name)
{ {
if (! $this->hasLoaded($name)) { if (!$this->hasLoaded($name)) {
throw new ProgrammingError( throw new ProgrammingError(
sprintf( sprintf(
'Cannot access module %s as it hasn\'t been loaded', 'Cannot access module %s as it hasn\'t been loaded',
@ -388,10 +391,10 @@ class Manager
* Return an array containing information objects for each available module * Return an array containing information objects for each available module
* *
* Each entry has the following fields * Each entry has the following fields
* - name: The name of the module as a string * * name, name of the module as a string
* - path: The path where the module is located as a string * * path, path where the module is located as a string
* - enabled: Whether the module is enabled or not as a boolean * * enabled, whether the module is enabled or not as a boolean
* - loaded: Whether the module is loaded or not as a boolean * * loaded, whether the module is loaded or not as a boolean
* *
* @return array * @return array
*/ */
@ -438,10 +441,11 @@ class Manager
/** /**
* Return an array containing all installled module names as strings * Return an array containing all installled module names as strings
* *
* Calls @see Manager::detectInstalledModules if no module discovery has * Calls detectInstalledModules() if no module discovery has been performed yet
* been performed yet
* *
* @return array * @return array
*
* @see detectInstalledModules()
*/ */
public function listInstalledModules() public function listInstalledModules()
{ {

View File

@ -43,54 +43,63 @@ class Module
{ {
/** /**
* Module name * Module name
*
* @var string * @var string
*/ */
private $name; private $name;
/** /**
* Base directory of module * Base directory of module
*
* @var string * @var string
*/ */
private $basedir; private $basedir;
/** /**
* Directory for styles * Directory for styles
*
* @var string * @var string
*/ */
private $cssdir; private $cssdir;
/** /**
* Library directory * Library directory
*
* @var string * @var string
*/ */
private $libdir; private $libdir;
/** /**
* Directory containing translations * Directory containing translations
*
* @var string * @var string
*/ */
private $localedir; private $localedir;
/** /**
* Directory where controllers reside * Directory where controllers reside
*
* @var string * @var string
*/ */
private $controllerdir; private $controllerdir;
/** /**
* Directory containing form implementations * Directory containing form implementations
*
* @var string * @var string
*/ */
private $formdir; private $formdir;
/** /**
* Module bootstrapping script * Module bootstrapping script
*
* @var string * @var string
*/ */
private $registerscript; private $registerscript;
/** /**
* Icinga application * Icinga application
*
* @var \Icinga\Application\Web * @var \Icinga\Application\Web
*/ */
private $app; private $app;
@ -98,9 +107,9 @@ class Module
/** /**
* Create a new module object * Create a new module object
* *
* @param ApplicationBootstrap $app * @param ApplicationBootstrap $app
* @param string $name * @param string $name
* @param string $basedir * @param string $basedir
*/ */
public function __construct(ApplicationBootstrap $app, $name, $basedir) public function __construct(ApplicationBootstrap $app, $name, $basedir)
{ {
@ -133,6 +142,7 @@ class Module
* Test for an enabled module by name * Test for an enabled module by name
* *
* @param string $name * @param string $name
*
* @return boolean * @return boolean
*/ */
public static function exists($name) public static function exists($name)
@ -145,8 +155,10 @@ class Module
* *
* @param string $name * @param string $name
* @param bool $autoload * @param bool $autoload
*
* @return mixed * @return mixed
* @throws \Icinga\Exception\ProgrammingError When the module is not yet loaded *
* @throws \Icinga\Exception\ProgrammingError When the module is not yet loaded
*/ */
public static function get($name, $autoload = false) public static function get($name, $autoload = false)
{ {
@ -238,7 +250,8 @@ class Module
/** /**
* Getter for module config object * Getter for module config object
* *
* @param null|string $file * @param string $file
*
* @return Config * @return Config
*/ */
public function getConfig($file = null) public function getConfig($file = null)
@ -373,9 +386,10 @@ class Module
/** /**
* Register hook * Register hook
* *
* @param string $name * @param string $name
* @param string $class * @param string $class
* @param string $key * @param string $key
*
* @return self * @return self
*/ */
protected function registerHook($name, $key, $class) protected function registerHook($name, $key, $class)

View File

@ -1,10 +1,14 @@
<?php <?php
// @codingStandardsIgnoreStart
// {{{ICINGA_LICENSE_HEADER}}}
// {{{ICINGA_LICENSE_HEADER}}}
use \Zend_Soap_Server as ZfSoapServer;
use \Zend_Soap_AutoDiscover as ZfSoapAutoDiscover;
use \Icinga\Web\Controller\ModuleActionController;
use \Icinga\Web\Url;
use \Monitoring\Backend;
use Icinga\Web\Controller\ModuleActionController;
use Icinga\Web\Url;
use Monitoring\Backend;
use Zend_Soap_Server as ZfSoapServer;
use Zend_Soap_AutoDiscover as ZfSoapAutoDiscover;
class Api class Api
{ {
@ -47,3 +51,4 @@ class Monitoring_SoapController extends ModuleActionController
exit; exit;
} }
} }
// @codingStandardsIgnoreEnd