X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=CRM%2FCore%2FManagedEntities.php;h=4de184a28c1b1d11092c1f98481327da4c5e87f4;hb=effbca4ff9428542add5a429ab3f492b07d52d92;hp=d8b3361b2b87772d98d07ddad032fdacd7fd47da;hpb=335f816e058ff3be3068bf312306fa875cc6d489;p=civicrm-core.git

diff --git a/CRM/Core/ManagedEntities.php b/CRM/Core/ManagedEntities.php
index d8b3361b2b..4de184a28c 100644
--- a/CRM/Core/ManagedEntities.php
+++ b/CRM/Core/ManagedEntities.php
@@ -7,6 +7,11 @@
  */
 class CRM_Core_ManagedEntities {
 
+  /**
+   * Get clean up options.
+   *
+   * @return array
+   */
   public static function getCleanupOptions() {
     return array(
       'always' => ts('Always'),
@@ -16,17 +21,20 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * @var array($status => array($name => CRM_Core_Module))
+   * @var array
+   *   Array($status => array($name => CRM_Core_Module)).
    */
   protected $moduleIndex;
 
   /**
-   * @var array per hook_civicrm_managed
+   * @var array
+   *   List of all entity declarations.
+   * @see CRM_Utils_Hook::managed()
    */
   protected $declarations;
 
   /**
-   * Get an instance
+   * Get an instance.
    * @param bool $fresh
    * @return \CRM_Core_ManagedEntities
    */
@@ -53,23 +61,31 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * @param array $modules CRM_Core_Module
-   * @param array $declarations per hook_civicrm_managed
+   * @param array $modules
+   *   CRM_Core_Module.
+   * @param array $declarations
+   *   Per hook_civicrm_managed.
    */
   public function __construct($modules, $declarations) {
     $this->moduleIndex = self::createModuleIndex($modules);
 
     if ($declarations !== NULL) {
       $this->declarations = self::cleanDeclarations($declarations);
-    } else {
+    }
+    else {
       $this->declarations = NULL;
     }
   }
 
   /**
-   * Read the managed entity
+   * Read a managed entity using APIv3.
    *
-   * @return array|NULL API representation, or NULL if the entity does not exist
+   * @param string $moduleName
+   *   The name of the module which declared entity.
+   * @param string $name
+   *   The symbolic name of the entity.
+   * @return array|NULL
+   *   API representation, or NULL if the entity does not exist
    */
   public function get($moduleName, $name) {
     $dao = new CRM_Core_DAO_Managed();
@@ -87,11 +103,18 @@ class CRM_Core_ManagedEntities {
         $this->onApiError($dao->entity_type, 'getsingle', $params, $result);
       }
       return $result;
-    } else {
+    }
+    else {
       return NULL;
     }
   }
 
+  /**
+   * Identify any enabled/disabled modules. Add new entities, update
+   * existing entities, and remove orphaned (stale) entities.
+   *
+   * @throws Exception
+   */
   public function reconcile() {
     if ($error = $this->validate($this->getDeclarations())) {
       throw new Exception($error);
@@ -101,7 +124,12 @@ class CRM_Core_ManagedEntities {
     $this->reconcileUnknownModules();
   }
 
-
+  /**
+   * For all enabled modules, add new entities, update
+   * existing entities, and remove orphaned (stale) entities.
+   *
+   * @throws Exception
+   */
   public function reconcileEnabledModules() {
     // Note: any thing currently declared is necessarily from
     // an active module -- because we got it from a hook!
@@ -111,19 +139,24 @@ class CRM_Core_ManagedEntities {
     foreach ($decls as $moduleName => $todos) {
       if (isset($this->moduleIndex[TRUE][$moduleName])) {
         $this->reconcileEnabledModule($this->moduleIndex[TRUE][$moduleName], $todos);
-      } elseif (isset($this->moduleIndex[FALSE][$moduleName])) {
+      }
+      elseif (isset($this->moduleIndex[FALSE][$moduleName])) {
         // do nothing -- module should get swept up later
-      } else {
+      }
+      else {
         throw new Exception("Entity declaration references invalid or inactive module name [$moduleName]");
       }
     }
   }
 
   /**
-   * Create, update, and delete entities declared by an active module
+   * For one enabled module, add new entities, update existing entities,
+   * and remove orphaned (stale) entities.
    *
-   * @param \CRM_Core_Module|string $module string
-   * @param $todos array $name => array()
+   * @param \CRM_Core_Module $module
+   * @param array $todos
+   *   List of entities currently declared by this module.
+   *   array(string $name => array $entityDef).
    */
   public function reconcileEnabledModule(CRM_Core_Module $module, $todos) {
     $dao = new CRM_Core_DAO_Managed();
@@ -134,7 +167,8 @@ class CRM_Core_ManagedEntities {
         // update existing entity; remove from $todos
         $this->updateExistingEntity($dao, $todos[$dao->name]);
         unset($todos[$dao->name]);
-      } else {
+      }
+      else {
         // remove stale entity; not in $todos
         $this->removeStaleEntity($dao);
       }
@@ -146,6 +180,9 @@ class CRM_Core_ManagedEntities {
     }
   }
 
+  /**
+   * For all disabled modules, disable any managed entities.
+   */
   public function reconcileDisabledModules() {
     if (empty($this->moduleIndex[FALSE])) {
       return;
@@ -161,6 +198,10 @@ class CRM_Core_ManagedEntities {
     }
   }
 
+  /**
+   * Remove any orphaned (stale) entities that are linked to
+   * unknown modules.
+   */
   public function reconcileUnknownModules() {
     $knownModules = array();
     if (array_key_exists(0, $this->moduleIndex) && is_array($this->moduleIndex[0])) {
@@ -168,7 +209,6 @@ class CRM_Core_ManagedEntities {
     }
     if (array_key_exists(1, $this->moduleIndex) && is_array($this->moduleIndex[1])) {
       $knownModules = array_merge($knownModules, array_keys($this->moduleIndex[1]));
-
     }
 
     $dao = new CRM_Core_DAO_Managed();
@@ -183,9 +223,10 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * Create a new entity
+   * Create a new entity.
    *
-   * @param array $todo entity specification (per hook_civicrm_managedEntities)
+   * @param array $todo
+   *   Entity specification (per hook_civicrm_managedEntities).
    */
   public function insertNewEntity($todo) {
     $result = civicrm_api($todo['entity'], 'create', $todo['params']);
@@ -206,7 +247,8 @@ class CRM_Core_ManagedEntities {
    * Update an entity which (a) is believed to exist and which (b) ought to be active.
    *
    * @param CRM_Core_DAO_Managed $dao
-   * @param array $todo entity specification (per hook_civicrm_managedEntities)
+   * @param array $todo
+   *   Entity specification (per hook_civicrm_managedEntities).
    */
   public function updateExistingEntity($dao, $todo) {
     $policy = CRM_Utils_Array::value('update', $todo, 'always');
@@ -220,7 +262,7 @@ class CRM_Core_ManagedEntities {
       $params = array_merge($defaults, $todo['params']);
       $result = civicrm_api($dao->entity_type, 'create', $params);
       if ($result['is_error']) {
-        $this->onApiError($dao->entity_type, 'create',$params, $result);
+        $this->onApiError($dao->entity_type, 'create', $params, $result);
       }
     }
 
@@ -247,15 +289,16 @@ class CRM_Core_ManagedEntities {
       );
       $result = civicrm_api($dao->entity_type, 'create', $params);
       if ($result['is_error']) {
-        $this->onApiError($dao->entity_type, 'create',$params, $result);
+        $this->onApiError($dao->entity_type, 'create', $params, $result);
       }
     }
   }
 
   /**
-   * Remove a stale entity (if policy allows)
+   * Remove a stale entity (if policy allows).
    *
    * @param CRM_Core_DAO_Managed $dao
+   * @throws Exception
    */
   public function removeStaleEntity($dao) {
     $policy = empty($dao->cleanup) ? 'always' : $dao->cleanup;
@@ -263,13 +306,15 @@ class CRM_Core_ManagedEntities {
       case 'always':
         $doDelete = TRUE;
         break;
+
       case 'never':
         $doDelete = FALSE;
         break;
+
       case 'unused':
         $getRefCount = civicrm_api3($dao->entity_type, 'getrefcount', array(
           'debug' => 1,
-          'id' => $dao->entity_id
+          'id' => $dao->entity_id,
         ));
 
         $total = 0;
@@ -279,6 +324,7 @@ class CRM_Core_ManagedEntities {
 
         $doDelete = ($total == 0);
         break;
+
       default:
         throw new \Exception('Unrecognized cleanup policy: ' . $policy);
     }
@@ -294,11 +340,16 @@ class CRM_Core_ManagedEntities {
       }
 
       CRM_Core_DAO::executeQuery('DELETE FROM civicrm_managed WHERE id = %1', array(
-        1 => array($dao->id, 'Integer')
+        1 => array($dao->id, 'Integer'),
       ));
     }
   }
 
+  /**
+   * Get declarations.
+   *
+   * @return array|null
+   */
   public function getDeclarations() {
     if ($this->declarations === NULL) {
       $this->declarations = array();
@@ -313,9 +364,11 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * @param $modules
+   * @param array $modules
+   *   Array<CRM_Core_Module>.
    *
-   * @return array indexed by is_active,name
+   * @return array
+   *   indexed by is_active,name
    */
   protected static function createModuleIndex($modules) {
     $result = array();
@@ -326,10 +379,11 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * @param $moduleIndex
-   * @param $declarations
+   * @param array $moduleIndex
+   * @param array $declarations
    *
-   * @return array indexed by module,name
+   * @return array
+   *   indexed by module,name
    */
   protected static function createDeclarationIndex($moduleIndex, $declarations) {
     $result = array();
@@ -351,7 +405,8 @@ class CRM_Core_ManagedEntities {
   /**
    * @param $declarations
    *
-   * @return mixed string on error, or FALSE
+   * @return string|bool
+   *   string on error, or FALSE
    */
   protected static function validate($declarations) {
     foreach ($declarations as $declare) {
@@ -367,9 +422,9 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * @param $declarations
+   * @param array $declarations
    *
-   * @return mixed
+   * @return array
    */
   protected static function cleanDeclarations($declarations) {
     foreach ($declarations as $name => &$declare) {
@@ -397,4 +452,5 @@ class CRM_Core_ManagedEntities {
     ));
     throw new Exception('API error: ' . $result['error_message']);
   }
+
 }