INFRA-132 - Docblock @param and @return tag fixes
[civicrm-core.git] / CRM / Core / Config.php
index 8a4ed0df0e48961cc08ee17b64b2407c29cc2036..3060cc137e469557fc31a8e77d09c55b7b142f1a 100644 (file)
@@ -1,7 +1,7 @@
 <?php
 /*
  +--------------------------------------------------------------------+
- | CiviCRM version 4.5                                                |
+ | CiviCRM version 4.6                                                |
  +--------------------------------------------------------------------+
  | Copyright CiviCRM LLC (c) 2004-2014                                |
  +--------------------------------------------------------------------+
@@ -50,28 +50,28 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   ///
 
   /**
-   * the dsn of the database connection
+   * The dsn of the database connection
    *
    * @var string
    */
   public $dsn;
 
   /**
-   * the name of user framework
+   * The name of user framework
    *
    * @var string
    */
   public $userFramework = 'Drupal';
 
   /**
-   * the name of user framework url variable name
+   * The name of user framework url variable name
    *
    * @var string
    */
   public $userFrameworkURLVar = 'q';
 
   /**
-   * the dsn of the database connection for user framework
+   * The dsn of the database connection for user framework
    *
    * @var string
    */
@@ -109,7 +109,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   ///
 
   /**
-   * are we initialized and in a proper state
+   * Are we initialized and in a proper state
    *
    * @var string
    */
@@ -121,7 +121,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   public $customPHPPathDir;
 
   /**
-   * the factory class used to instantiate our DB objects
+   * The factory class used to instantiate our DB objects
    *
    * @var string
    */
@@ -134,7 +134,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   private static $_log = NULL;
 
   /**
-   * the handle on the mail handler that we are using
+   * The handle on the mail handler that we are using
    *
    * @var object
    */
@@ -187,13 +187,15 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   /**
    * Singleton function used to manage this object.
    *
-   * @param $loadFromDB boolean  whether to load from the database
-   * @param $force      boolean  whether to force a reconstruction
+   * @param bool $loadFromDB
+   *   whether to load from the database.
+   * @param bool $force
+   *   whether to force a reconstruction.
    *
    * @return CRM_Core_Config
    * @static
    */
-  static function &singleton($loadFromDB = TRUE, $force = FALSE) {
+  public static function &singleton($loadFromDB = TRUE, $force = FALSE) {
     if (self::$_singleton === NULL || $force) {
       // goto a simple error handler
       $GLOBALS['civicrm_default_error_scope'] = CRM_Core_TemporaryErrorScope::create(array('CRM_Core_Error', 'handle'));
@@ -401,10 +403,9 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * initialize the DataObject framework
+   * Initialize the DataObject framework
    *
    * @return void
-   * @access private
    */
   private function _initDAO() {
     CRM_Core_DAO::init($this->dsn);
@@ -418,10 +419,9 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * returns the singleton logger for the application
+   * Returns the singleton logger for the application
    *
    * @param
-   * @access private
    *
    * @return object
    */
@@ -434,10 +434,9 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * initialize the config variables
+   * Initialize the config variables
    *
    * @return void
-   * @access private
    */
   private function _initVariables() {
     // retrieve serialised settings
@@ -485,7 +484,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
           $url = CRM_Utils_System::url('civicrm/admin/setting/path', 'reset=1');
           CRM_Core_Session::setStatus(ts('%1 has an incorrect directory path. Please go to the <a href="%2">path setting page</a> and correct it.', array(
             1 => $key,
-            2 => $url
+            2 => $url,
           )), ts('Check Settings'), 'alert');
         }
       }
@@ -528,7 +527,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
       $this->geocodeMethod = 'CRM_Utils_Geocode_' . $this->mapProvider;
     }
 
-    require_once (str_replace('_', DIRECTORY_SEPARATOR, $this->userFrameworkClass) . '.php');
+    require_once str_replace('_', DIRECTORY_SEPARATOR, $this->userFrameworkClass) . '.php';
     $class = $this->userFrameworkClass;
     // redundant with _setUserFrameworkConfig
     $this->userSystem = new $class();
@@ -537,11 +536,11 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   /**
    * Retrieve a mailer to send any mail from the application
    *
-   * @param boolean $persist open a persistent smtp connection, should speed up mailings
-   * @access private
+   * @param bool $persist
+   *   Open a persistent smtp connection, should speed up mailings.
    * @return object
    */
-  static function &getMailer($persist = FALSE) {
+  public static function &getMailer($persist = FALSE) {
     if (!isset(self::$_mail)) {
       $mailingInfo = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::MAILING_PREFERENCES_NAME,
         'mailing_backend'
@@ -616,9 +615,11 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   /**
    * Create a new instance of a PEAR Mail driver
    *
-   * @param string $driver 'CRM_Mailing_BAO_Spool' or a name suitable for Mail::factory()
+   * @param string $driver
+   *   'CRM_Mailing_BAO_Spool' or a name suitable for Mail::factory().
    * @param array $params
-   * @return Mail (More specifically, a class which implements the "send()" function)
+   * @return object
+   *   More specifically, a class which implements the "send()" function
    */
   public static function _createMailer($driver, $params) {
     if ($driver == 'CRM_Mailing_BAO_Spool') {
@@ -654,7 +655,12 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
 
     // Whether we delete/create or simply preserve directories, we should
     // certainly make sure the restrictions are enforced.
-    foreach (array($this->templateCompileDir, $this->uploadDir, $this->configAndLogDir, $this->customFileUploadDir) as $dir) {
+    foreach (array(
+               $this->templateCompileDir,
+               $this->uploadDir,
+               $this->configAndLogDir,
+               $this->customFileUploadDir
+             ) as $dir) {
       if ($dir && is_dir($dir)) {
         CRM_Utils_File::restrictAccess($dir);
       }
@@ -662,16 +668,15 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * verify that the needed parameters are not null in the config
+   * Verify that the needed parameters are not null in the config
    *
    * @param CRM_Core_Config (reference ) the system config object
-   * @param array           (reference ) the parameters that need a value
+   * @param array (reference ) the parameters that need a value
    *
    * @return boolean
    * @static
-   * @access public
    */
-  static function check(&$config, &$required) {
+  public static function check(&$config, &$required) {
     foreach ($required as $name) {
       if (CRM_Utils_System::isNull($config->$name)) {
         return FALSE;
@@ -681,16 +686,16 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * reset the serialized array and recompute
+   * Reset the serialized array and recompute
    * use with care
    */
-  function reset() {
+  public function reset() {
     $query = "UPDATE civicrm_domain SET config_backend = null";
     CRM_Core_DAO::executeQuery($query);
   }
 
   // This method should initialize auth sources
-  function initAuthSrc() {
+  public function initAuthSrc() {
     $session = CRM_Core_Session::singleton();
     if ($session->get('userID') && !$session->get('authSrc')) {
       $session->set('authSrc', CRM_Core_Permission::AUTH_SRC_LOGIN);
@@ -701,9 +706,9 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * one function to get domain ID
+   * One function to get domain ID
    */
-  static function domainID($domainID = NULL, $reset = FALSE) {
+  public static function domainID($domainID = NULL, $reset = FALSE) {
     static $domain;
     if ($domainID) {
       $domain = $domainID;
@@ -716,10 +721,10 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * do general cleanup of caches, temp directories and temp tables
+   * Do general cleanup of caches, temp directories and temp tables
    * CRM-8739
    */
-  function cleanupCaches($sessionReset = TRUE) {
+  public function cleanupCaches($sessionReset = TRUE) {
     // cleanup templates_c directory
     $this->cleanup(1, FALSE);
 
@@ -735,14 +740,15 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   /**
    * Do general cleanup of module permissions.
    */
-  function cleanupPermissions() {
+  public function cleanupPermissions() {
     $module_files = CRM_Extension_System::singleton()->getMapper()->getActiveModuleFiles();
     if ($this->userPermissionClass->isModulePermissionSupported()) {
       // Can store permissions -- so do it!
       $this->userPermissionClass->upgradePermissions(
         CRM_Core_Permission::basicPermissions()
       );
-    } else {
+    }
+    else {
       // Cannot store permissions -- warn if any modules require them
       $modules_with_perms = array();
       foreach ($module_files as $module_file) {
@@ -764,7 +770,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   /**
    * Flush information about loaded modules
    */
-  function clearModuleList() {
+  public function clearModuleList() {
     CRM_Extension_System::singleton()->getCache()->flush();
     CRM_Utils_Hook::singleton(TRUE);
     CRM_Core_PseudoConstant::getModuleExtensions(TRUE);
@@ -772,7 +778,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * clear db cache
+   * Clear db cache
    */
   public static function clearDBCache() {
     $queries = array(
@@ -796,7 +802,7 @@ class CRM_Core_Config extends CRM_Core_Config_Variables {
   }
 
   /**
-   * clear leftover temporary tables
+   * Clear leftover temporary tables
    */
   public static function clearTempTables() {
     // CRM-5645
@@ -827,9 +833,9 @@ AND
   }
 
   /**
-   * function to check if running in upgrade mode
+   * Check if running in upgrade mode
    */
-  static function isUpgradeMode($path = NULL) {
+  public static function isUpgradeMode($path = NULL) {
     if (defined('CIVICRM_UPGRADE_ACTIVE')) {
       return TRUE;
     }
@@ -863,9 +869,11 @@ AND
   /**
    * Is back office credit card processing enabled for this site - ie are there any installed processors that support
    * it?
+   * This function is used for determining whether to show the submit credit card link, not for determining which processors to show, hence
+   * it is a config var
    * @return bool
    */
-  static function isEnabledBackOfficeCreditCardPayments() {
+  public static function isEnabledBackOfficeCreditCardPayments() {
     return CRM_Financial_BAO_PaymentProcessor::hasPaymentProcessorSupporting(array('BackOffice'));
   }
 }