CRM/Core/ManagedEntities.php

   1 <?php
   2
   3 /**
   4  * The ManagedEntities system allows modules to add records to the database
   5  * declaratively.  Those records will be automatically inserted, updated,
   6  * deactivated, and deleted in tandem with their modules.
   7  */
   8 class CRM_Core_ManagedEntities {
   9
  10   public static function getCleanupOptions() {
  11     return array(
  12       'always' => ts('Always'),
  13       'never' => ts('Never'),
  14       'unused' => ts('If Unused'),
  15     );
  16   }
  17
  18   /**
  19    * @var array($status => array($name => CRM_Core_Module))
  20    */
  21   protected $moduleIndex;
  22
  23   /**
  24    * @var array per hook_civicrm_managed
  25    */
  26   protected $declarations;
  27
  28   /**
  29    * Get an instance
  30    * @param bool $fresh
  31    * @return \CRM_Core_ManagedEntities
  32    */
  33   public static function singleton($fresh = FALSE) {
  34     static $singleton;
  35     if ($fresh || !$singleton) {
  36       $singleton = new CRM_Core_ManagedEntities(CRM_Core_Module::getAll(), NULL);
  37     }
  38     return $singleton;
  39   }
  40
  41   /**
  42    * Perform an asynchronous reconciliation when the transaction ends.
  43    */
  44   public static function scheduleReconciliation() {
  45     CRM_Core_Transaction::addCallback(
  46       CRM_Core_Transaction::PHASE_POST_COMMIT,
  47       function () {
  48         CRM_Core_ManagedEntities::singleton(TRUE)->reconcile();
  49       },
  50       array(),
  51       'ManagedEntities::reconcile'
  52     );
  53   }
  54
  55   /**
  56    * @param array $modules
  57    *   CRM_Core_Module.
  58    * @param array $declarations
  59    *   Per hook_civicrm_managed.
  60    */
  61   public function __construct($modules, $declarations) {
  62     $this->moduleIndex = self::createModuleIndex($modules);
  63
  64     if ($declarations !== NULL) {
  65       $this->declarations = self::cleanDeclarations($declarations);
  66     }
  67     else {
  68       $this->declarations = NULL;
  69     }
  70   }
  71
  72   /**
  73    * Read the managed entity
  74    *
  75    * @return array|NULL API representation, or NULL if the entity does not exist
  76    */
  77   public function get($moduleName, $name) {
  78     $dao = new CRM_Core_DAO_Managed();
  79     $dao->module = $moduleName;
  80     $dao->name = $name;
  81     if ($dao->find(TRUE)) {
  82       $params = array(
  83         'id' => $dao->entity_id,
  84       );
  85       $result = NULL;
  86       try {
  87         $result = civicrm_api3($dao->entity_type, 'getsingle', $params);
  88       }
  89       catch (Exception $e) {
  90         $this->onApiError($dao->entity_type, 'getsingle', $params, $result);
  91       }
  92       return $result;
  93     }
  94     else {
  95       return NULL;
  96     }
  97   }
  98
  99   public function reconcile() {
 100     if ($error = $this->validate($this->getDeclarations())) {
 101       throw new Exception($error);
 102     }
 103     $this->reconcileEnabledModules();
 104     $this->reconcileDisabledModules();
 105     $this->reconcileUnknownModules();
 106   }
 107
 108
 109   public function reconcileEnabledModules() {
 110     // Note: any thing currently declared is necessarily from
 111     // an active module -- because we got it from a hook!
 112
 113     // index by moduleName,name
 114     $decls = self::createDeclarationIndex($this->moduleIndex, $this->getDeclarations());
 115     foreach ($decls as $moduleName => $todos) {
 116       if (isset($this->moduleIndex[TRUE][$moduleName])) {
 117         $this->reconcileEnabledModule($this->moduleIndex[TRUE][$moduleName], $todos);
 118       }
 119       elseif (isset($this->moduleIndex[FALSE][$moduleName])) {
 120         // do nothing -- module should get swept up later
 121       }
 122       else {
 123         throw new Exception("Entity declaration references invalid or inactive module name [$moduleName]");
 124       }
 125     }
 126   }
 127
 128   /**
 129    * Create, update, and delete entities declared by an active module
 130    *
 131    * @param \CRM_Core_Module|string $module string
 132    * @param $todos
 133    *   Array $name => array().
 134    */
 135   public function reconcileEnabledModule(CRM_Core_Module $module, $todos) {
 136     $dao = new CRM_Core_DAO_Managed();
 137     $dao->module = $module->name;
 138     $dao->find();
 139     while ($dao->fetch()) {
 140       if (isset($todos[$dao->name]) && $todos[$dao->name]) {
 141         // update existing entity; remove from $todos
 142         $this->updateExistingEntity($dao, $todos[$dao->name]);
 143         unset($todos[$dao->name]);
 144       }
 145       else {
 146         // remove stale entity; not in $todos
 147         $this->removeStaleEntity($dao);
 148       }
 149     }
 150
 151     // create new entities from leftover $todos
 152     foreach ($todos as $name => $todo) {
 153       $this->insertNewEntity($todo);
 154     }
 155   }
 156
 157   public function reconcileDisabledModules() {
 158     if (empty($this->moduleIndex[FALSE])) {
 159       return;
 160     }
 161
 162     $in = CRM_Core_DAO::escapeStrings(array_keys($this->moduleIndex[FALSE]));
 163     $dao = new CRM_Core_DAO_Managed();
 164     $dao->whereAdd("module in ($in)");
 165     $dao->find();
 166     while ($dao->fetch()) {
 167       $this->disableEntity($dao);
 168
 169     }
 170   }
 171
 172   public function reconcileUnknownModules() {
 173     $knownModules = array();
 174     if (array_key_exists(0, $this->moduleIndex) && is_array($this->moduleIndex[0])) {
 175       $knownModules = array_merge($knownModules, array_keys($this->moduleIndex[0]));
 176     }
 177     if (array_key_exists(1, $this->moduleIndex) && is_array($this->moduleIndex[1])) {
 178       $knownModules = array_merge($knownModules, array_keys($this->moduleIndex[1]));
 179
 180     }
 181
 182     $dao = new CRM_Core_DAO_Managed();
 183     if (!empty($knownModules)) {
 184       $in = CRM_Core_DAO::escapeStrings($knownModules);
 185       $dao->whereAdd("module NOT IN ($in)");
 186     }
 187     $dao->find();
 188     while ($dao->fetch()) {
 189       $this->removeStaleEntity($dao);
 190     }
 191   }
 192
 193   /**
 194    * Create a new entity
 195    *
 196    * @param array $todo
 197    *   Entity specification (per hook_civicrm_managedEntities).
 198    */
 199   public function insertNewEntity($todo) {
 200     $result = civicrm_api($todo['entity'], 'create', $todo['params']);
 201     if ($result['is_error']) {
 202       $this->onApiError($todo['entity'], 'create', $todo['params'], $result);
 203     }
 204
 205     $dao = new CRM_Core_DAO_Managed();
 206     $dao->module = $todo['module'];
 207     $dao->name = $todo['name'];
 208     $dao->entity_type = $todo['entity'];
 209     $dao->entity_id = $result['id'];
 210     $dao->cleanup = CRM_Utils_Array::value('cleanup', $todo);
 211     $dao->save();
 212   }
 213
 214   /**
 215    * Update an entity which (a) is believed to exist and which (b) ought to be active.
 216    *
 217    * @param CRM_Core_DAO_Managed $dao
 218    * @param array $todo
 219    *   Entity specification (per hook_civicrm_managedEntities).
 220    */
 221   public function updateExistingEntity($dao, $todo) {
 222     $policy = CRM_Utils_Array::value('update', $todo, 'always');
 223     $doUpdate = ($policy == 'always');
 224
 225     if ($doUpdate) {
 226       $defaults = array(
 227         'id' => $dao->entity_id,
 228         'is_active' => 1, // FIXME: test whether is_active is valid
 229       );
 230       $params = array_merge($defaults, $todo['params']);
 231       $result = civicrm_api($dao->entity_type, 'create', $params);
 232       if ($result['is_error']) {
 233         $this->onApiError($dao->entity_type, 'create',$params, $result);
 234       }
 235     }
 236
 237     if (isset($todo['cleanup'])) {
 238       $dao->cleanup = $todo['cleanup'];
 239       $dao->update();
 240     }
 241   }
 242
 243   /**
 244    * Update an entity which (a) is believed to exist and which (b) ought to be
 245    * inactive.
 246    *
 247    * @param CRM_Core_DAO_Managed $dao
 248    */
 249   public function disableEntity($dao) {
 250     // FIXME: if ($dao->entity_type supports is_active) {
 251     if (TRUE) {
 252       // FIXME cascading for payproc types?
 253       $params = array(
 254         'version' => 3,
 255         'id' => $dao->entity_id,
 256         'is_active' => 0,
 257       );
 258       $result = civicrm_api($dao->entity_type, 'create', $params);
 259       if ($result['is_error']) {
 260         $this->onApiError($dao->entity_type, 'create',$params, $result);
 261       }
 262     }
 263   }
 264
 265   /**
 266    * Remove a stale entity (if policy allows)
 267    *
 268    * @param CRM_Core_DAO_Managed $dao
 269    */
 270   public function removeStaleEntity($dao) {
 271     $policy = empty($dao->cleanup) ? 'always' : $dao->cleanup;
 272     switch ($policy) {
 273       case 'always':
 274         $doDelete = TRUE;
 275         break;
 276       case 'never':
 277         $doDelete = FALSE;
 278         break;
 279       case 'unused':
 280         $getRefCount = civicrm_api3($dao->entity_type, 'getrefcount', array(
 281           'debug' => 1,
 282           'id' => $dao->entity_id
 283         ));
 284
 285         $total = 0;
 286         foreach ($getRefCount['values'] as $refCount) {
 287           $total += $refCount['count'];
 288         }
 289
 290         $doDelete = ($total == 0);
 291         break;
 292       default:
 293         throw new \Exception('Unrecognized cleanup policy: ' . $policy);
 294     }
 295
 296     if ($doDelete) {
 297       $params = array(
 298         'version' => 3,
 299         'id' => $dao->entity_id,
 300       );
 301       $result = civicrm_api($dao->entity_type, 'delete', $params);
 302       if ($result['is_error']) {
 303         $this->onApiError($dao->entity_type, 'delete', $params, $result);
 304       }
 305
 306       CRM_Core_DAO::executeQuery('DELETE FROM civicrm_managed WHERE id = %1', array(
 307         1 => array($dao->id, 'Integer')
 308       ));
 309     }
 310   }
 311
 312   public function getDeclarations() {
 313     if ($this->declarations === NULL) {
 314       $this->declarations = array();
 315       foreach (CRM_Core_Component::getEnabledComponents() as $component) {
 316         /** @var CRM_Core_Component_Info $component */
 317         $this->declarations = array_merge($this->declarations, $component->getManagedEntities());
 318       }
 319       CRM_Utils_Hook::managed($this->declarations);
 320       $this->declarations = self::cleanDeclarations($this->declarations);
 321     }
 322     return $this->declarations;
 323   }
 324
 325   /**
 326    * @param $modules
 327    *
 328    * @return array indexed by is_active,name
 329    */
 330   protected static function createModuleIndex($modules) {
 331     $result = array();
 332     foreach ($modules as $module) {
 333       $result[$module->is_active][$module->name] = $module;
 334     }
 335     return $result;
 336   }
 337
 338   /**
 339    * @param $moduleIndex
 340    * @param $declarations
 341    *
 342    * @return array indexed by module,name
 343    */
 344   protected static function createDeclarationIndex($moduleIndex, $declarations) {
 345     $result = array();
 346     if (!isset($moduleIndex[TRUE])) {
 347       return $result;
 348     }
 349     foreach ($moduleIndex[TRUE] as $moduleName => $module) {
 350       if ($module->is_active) {
 351         // need an empty array() for all active modules, even if there are no current $declarations
 352         $result[$moduleName] = array();
 353       }
 354     }
 355     foreach ($declarations as $declaration) {
 356       $result[$declaration['module']][$declaration['name']] = $declaration;
 357     }
 358     return $result;
 359   }
 360
 361   /**
 362    * @param $declarations
 363    *
 364    * @return mixed string on error, or FALSE
 365    */
 366   protected static function validate($declarations) {
 367     foreach ($declarations as $declare) {
 368       foreach (array('name', 'module', 'entity', 'params') as $key) {
 369         if (empty($declare[$key])) {
 370           $str = print_r($declare, TRUE);
 371           return ("Managed Entity is missing field \"$key\": $str");
 372         }
 373       }
 374       // FIXME: validate that each 'module' is known
 375     }
 376     return FALSE;
 377   }
 378
 379   /**
 380    * @param $declarations
 381    *
 382    * @return mixed
 383    */
 384   protected static function cleanDeclarations($declarations) {
 385     foreach ($declarations as $name => &$declare) {
 386       if (!array_key_exists('name', $declare)) {
 387         $declare['name'] = $name;
 388       }
 389     }
 390     return $declarations;
 391   }
 392
 393   /**
 394    * @param string $entity
 395    * @param string $action
 396    * @param array $params
 397    * @param array $result
 398    *
 399    * @throws Exception
 400    */
 401   protected function onApiError($entity, $action, $params, $result) {
 402     CRM_Core_Error::debug_var('ManagedEntities_failed', array(
 403       'entity' => $entity,
 404       'action' => $action,
 405       'params' => $params,
 406       'result' => $result,
 407     ));
 408     throw new Exception('API error: ' . $result['error_message']);
 409   }
 410 }