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

diff --git a/CRM/Core/ManagedEntities.php b/CRM/Core/ManagedEntities.php
index ca4deb4f27..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
    */
@@ -70,9 +78,14 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * 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();
@@ -96,6 +109,12 @@ class CRM_Core_ManagedEntities {
     }
   }
 
+  /**
+   * 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);
@@ -105,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!
@@ -126,11 +150,13 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * 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();
@@ -154,6 +180,9 @@ class CRM_Core_ManagedEntities {
     }
   }
 
+  /**
+   * For all disabled modules, disable any managed entities.
+   */
   public function reconcileDisabledModules() {
     if (empty($this->moduleIndex[FALSE])) {
       return;
@@ -169,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])) {
@@ -176,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();
@@ -191,7 +223,7 @@ class CRM_Core_ManagedEntities {
   }
 
   /**
-   * Create a new entity
+   * Create a new entity.
    *
    * @param array $todo
    *   Entity specification (per hook_civicrm_managedEntities).
@@ -230,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);
       }
     }
 
@@ -257,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;
@@ -273,9 +306,11 @@ 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,
@@ -289,6 +324,7 @@ class CRM_Core_ManagedEntities {
 
         $doDelete = ($total == 0);
         break;
+
       default:
         throw new \Exception('Unrecognized cleanup policy: ' . $policy);
     }
@@ -309,6 +345,11 @@ class CRM_Core_ManagedEntities {
     }
   }
 
+  /**
+   * Get declarations.
+   *
+   * @return array|null
+   */
   public function getDeclarations() {
     if ($this->declarations === NULL) {
       $this->declarations = array();
@@ -323,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();
@@ -336,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();
@@ -361,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) {
@@ -377,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) {
@@ -407,4 +452,5 @@ class CRM_Core_ManagedEntities {
     ));
     throw new Exception('API error: ' . $result['error_message']);
   }
+
 }