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   /**
  11    * Get clean up options.
  12    *
  13    * @return array
  14    */
  15   public static function getCleanupOptions() {
  16     return [
  17       'always' => ts('Always'),
  18       'never' => ts('Never'),
  19       'unused' => ts('If Unused'),
  20     ];
  21   }
  22
  23   /**
  24    * @var array
  25    *   Array($status => array($name => CRM_Core_Module)).
  26    */
  27   protected $moduleIndex;
  28
  29   /**
  30    * @var array
  31    *   List of all entity declarations.
  32    * @see CRM_Utils_Hook::managed()
  33    */
  34   protected $declarations;
  35
  36   /**
  37    * Get an instance.
  38    * @param bool $fresh
  39    * @return \CRM_Core_ManagedEntities
  40    */
  41   public static function singleton($fresh = FALSE) {
  42     static $singleton;
  43     if ($fresh || !$singleton) {
  44       $singleton = new CRM_Core_ManagedEntities(CRM_Core_Module::getAll(), NULL);
  45     }
  46     return $singleton;
  47   }
  48
  49   /**
  50    * Perform an asynchronous reconciliation when the transaction ends.
  51    */
  52   public static function scheduleReconciliation() {
  53     CRM_Core_Transaction::addCallback(
  54       CRM_Core_Transaction::PHASE_POST_COMMIT,
  55       function () {
  56         CRM_Core_ManagedEntities::singleton(TRUE)->reconcile();
  57       },
  58       [],
  59       'ManagedEntities::reconcile'
  60     );
  61   }
  62
  63   /**
  64    * @param array $modules
  65    *   CRM_Core_Module.
  66    * @param array $declarations
  67    *   Per hook_civicrm_managed.
  68    */
  69   public function __construct($modules, $declarations) {
  70     $this->moduleIndex = self::createModuleIndex($modules);
  71
  72     if ($declarations !== NULL) {
  73       $this->declarations = self::cleanDeclarations($declarations);
  74     }
  75     else {
  76       $this->declarations = NULL;
  77     }
  78   }
  79
  80   /**
  81    * Read a managed entity using APIv3.
  82    *
  83    * @param string $moduleName
  84    *   The name of the module which declared entity.
  85    * @param string $name
  86    *   The symbolic name of the entity.
  87    * @return array|NULL
  88    *   API representation, or NULL if the entity does not exist
  89    */
  90   public function get($moduleName, $name) {
  91     $dao = new CRM_Core_DAO_Managed();
  92     $dao->module = $moduleName;
  93     $dao->name = $name;
  94     if ($dao->find(TRUE)) {
  95       $params = [
  96         'id' => $dao->entity_id,
  97       ];
  98       $result = NULL;
  99       try {
 100         $result = civicrm_api3($dao->entity_type, 'getsingle', $params);
 101       }
 102       catch (Exception $e) {
 103         $this->onApiError($dao->entity_type, 'getsingle', $params, $result);
 104       }
 105       return $result;
 106     }
 107     else {
 108       return NULL;
 109     }
 110   }
 111
 112   /**
 113    * Identify any enabled/disabled modules. Add new entities, update
 114    * existing entities, and remove orphaned (stale) entities.
 115    * @param bool $ignoreUpgradeMode
 116    *
 117    * @throws Exception
 118    */
 119   public function reconcile($ignoreUpgradeMode = FALSE) {
 120     // Do not reconcile whilst we are in upgrade mode
 121     if (CRM_Core_Config::singleton()->isUpgradeMode() && !$ignoreUpgradeMode) {
 122       return;
 123     }
 124     if ($error = $this->validate($this->getDeclarations())) {
 125       throw new Exception($error);
 126     }
 127     $this->reconcileEnabledModules();
 128     $this->reconcileDisabledModules();
 129     $this->reconcileUnknownModules();
 130   }
 131
 132   /**
 133    * For all enabled modules, add new entities, update
 134    * existing entities, and remove orphaned (stale) entities.
 135    *
 136    * @throws Exception
 137    */
 138   public function reconcileEnabledModules() {
 139     // Note: any thing currently declared is necessarily from
 140     // an active module -- because we got it from a hook!
 141
 142     // index by moduleName,name
 143     $decls = self::createDeclarationIndex($this->moduleIndex, $this->getDeclarations());
 144     foreach ($decls as $moduleName => $todos) {
 145       if (isset($this->moduleIndex[TRUE][$moduleName])) {
 146         $this->reconcileEnabledModule($this->moduleIndex[TRUE][$moduleName], $todos);
 147       }
 148       elseif (isset($this->moduleIndex[FALSE][$moduleName])) {
 149         // do nothing -- module should get swept up later
 150       }
 151       else {
 152         throw new Exception("Entity declaration references invalid or inactive module name [$moduleName]");
 153       }
 154     }
 155   }
 156
 157   /**
 158    * For one enabled module, add new entities, update existing entities,
 159    * and remove orphaned (stale) entities.
 160    *
 161    * @param \CRM_Core_Module $module
 162    * @param array $todos
 163    *   List of entities currently declared by this module.
 164    *   array(string $name => array $entityDef).
 165    */
 166   public function reconcileEnabledModule(CRM_Core_Module $module, $todos) {
 167     $dao = new CRM_Core_DAO_Managed();
 168     $dao->module = $module->name;
 169     $dao->find();
 170     while ($dao->fetch()) {
 171       if (isset($todos[$dao->name]) && $todos[$dao->name]) {
 172         // update existing entity; remove from $todos
 173         $this->updateExistingEntity($dao, $todos[$dao->name]);
 174         unset($todos[$dao->name]);
 175       }
 176       else {
 177         // remove stale entity; not in $todos
 178         $this->removeStaleEntity($dao);
 179       }
 180     }
 181
 182     // create new entities from leftover $todos
 183     foreach ($todos as $name => $todo) {
 184       $this->insertNewEntity($todo);
 185     }
 186   }
 187
 188   /**
 189    * For all disabled modules, disable any managed entities.
 190    */
 191   public function reconcileDisabledModules() {
 192     if (empty($this->moduleIndex[FALSE])) {
 193       return;
 194     }
 195
 196     $in = CRM_Core_DAO::escapeStrings(array_keys($this->moduleIndex[FALSE]));
 197     $dao = new CRM_Core_DAO_Managed();
 198     $dao->whereAdd("module in ($in)");
 199     $dao->orderBy('id DESC');
 200     $dao->find();
 201     while ($dao->fetch()) {
 202       $this->disableEntity($dao);
 203
 204     }
 205   }
 206
 207   /**
 208    * Remove any orphaned (stale) entities that are linked to
 209    * unknown modules.
 210    */
 211   public function reconcileUnknownModules() {
 212     $knownModules = [];
 213     if (array_key_exists(0, $this->moduleIndex) && is_array($this->moduleIndex[0])) {
 214       $knownModules = array_merge($knownModules, array_keys($this->moduleIndex[0]));
 215     }
 216     if (array_key_exists(1, $this->moduleIndex) && is_array($this->moduleIndex[1])) {
 217       $knownModules = array_merge($knownModules, array_keys($this->moduleIndex[1]));
 218     }
 219
 220     $dao = new CRM_Core_DAO_Managed();
 221     if (!empty($knownModules)) {
 222       $in = CRM_Core_DAO::escapeStrings($knownModules);
 223       $dao->whereAdd("module NOT IN ($in)");
 224       $dao->orderBy('id DESC');
 225     }
 226     $dao->find();
 227     while ($dao->fetch()) {
 228       $this->removeStaleEntity($dao);
 229     }
 230   }
 231
 232   /**
 233    * Create a new entity.
 234    *
 235    * @param array $todo
 236    *   Entity specification (per hook_civicrm_managedEntities).
 237    */
 238   public function insertNewEntity($todo) {
 239     $result = civicrm_api($todo['entity'], 'create', $todo['params']);
 240     if (!empty($result['is_error'])) {
 241       $this->onApiError($todo['entity'], 'create', $todo['params'], $result);
 242     }
 243
 244     $dao = new CRM_Core_DAO_Managed();
 245     $dao->module = $todo['module'];
 246     $dao->name = $todo['name'];
 247     $dao->entity_type = $todo['entity'];
 248     // A fatal error will result if there is no valid id but if
 249     // this is v4 api we might need to access it via ->first().
 250     $dao->entity_id = $result['id'] ?? $result->first()['id'];
 251     $dao->cleanup = $todo['cleanup'] ?? NULL;
 252     $dao->save();
 253   }
 254
 255   /**
 256    * Update an entity which is believed to exist.
 257    *
 258    * @param CRM_Core_DAO_Managed $dao
 259    * @param array $todo
 260    *   Entity specification (per hook_civicrm_managedEntities).
 261    */
 262   public function updateExistingEntity($dao, $todo) {
 263     $policy = CRM_Utils_Array::value('update', $todo, 'always');
 264     $doUpdate = ($policy === 'always');
 265
 266     if ($doUpdate) {
 267       $defaults = ['id' => $dao->entity_id];
 268       if ($this->isActivationSupported($dao->entity_type)) {
 269         $defaults['is_active'] = 1;
 270       }
 271       $params = array_merge($defaults, $todo['params']);
 272
 273       $manager = CRM_Extension_System::singleton()->getManager();
 274       if ($dao->entity_type === 'Job' && !$manager->extensionIsBeingInstalledOrEnabled($dao->module)) {
 275         // Special treatment for scheduled jobs:
 276         //
 277         // If we're being called as part of enabling/installing a module then
 278         // we want the default behaviour of setting is_active = 1.
 279         //
 280         // However, if we're just being called by a normal cache flush then we
 281         // should not re-enable a job that an administrator has decided to disable.
 282         //
 283         // Without this logic there was a problem: site admin might disable
 284         // a job, but then when there was a flush op, the job was re-enabled
 285         // which can cause significant embarrassment, depending on the job
 286         // ("Don't worry, sending mailings is disabled right now...").
 287         unset($params['is_active']);
 288       }
 289
 290       $result = civicrm_api($dao->entity_type, 'create', $params);
 291       if ($result['is_error']) {
 292         $this->onApiError($dao->entity_type, 'create', $params, $result);
 293       }
 294     }
 295
 296     if (isset($todo['cleanup'])) {
 297       $dao->cleanup = $todo['cleanup'];
 298       $dao->update();
 299     }
 300   }
 301
 302   /**
 303    * Update an entity which (a) is believed to exist and which (b) ought to be
 304    * inactive.
 305    *
 306    * @param CRM_Core_DAO_Managed $dao
 307    *
 308    * @throws \CiviCRM_API3_Exception
 309    */
 310   public function disableEntity($dao): void {
 311     $entity_type = $dao->entity_type;
 312     if ($this->isActivationSupported($entity_type)) {
 313       // FIXME cascading for payproc types?
 314       $params = [
 315         'version' => 3,
 316         'id' => $dao->entity_id,
 317         'is_active' => 0,
 318       ];
 319       $result = civicrm_api($dao->entity_type, 'create', $params);
 320       if ($result['is_error']) {
 321         $this->onApiError($dao->entity_type, 'create', $params, $result);
 322       }
 323     }
 324   }
 325
 326   /**
 327    * Remove a stale entity (if policy allows).
 328    *
 329    * @param CRM_Core_DAO_Managed $dao
 330    * @throws Exception
 331    */
 332   public function removeStaleEntity($dao) {
 333     $policy = empty($dao->cleanup) ? 'always' : $dao->cleanup;
 334     switch ($policy) {
 335       case 'always':
 336         $doDelete = TRUE;
 337         break;
 338
 339       case 'never':
 340         $doDelete = FALSE;
 341         break;
 342
 343       case 'unused':
 344         $getRefCount = civicrm_api3($dao->entity_type, 'getrefcount', [
 345           'debug' => 1,
 346           'id' => $dao->entity_id,
 347         ]);
 348
 349         $total = 0;
 350         foreach ($getRefCount['values'] as $refCount) {
 351           $total += $refCount['count'];
 352         }
 353
 354         $doDelete = ($total == 0);
 355         break;
 356
 357       default:
 358         throw new \Exception('Unrecognized cleanup policy: ' . $policy);
 359     }
 360
 361     if ($doDelete) {
 362       $params = [
 363         'version' => 3,
 364         'id' => $dao->entity_id,
 365       ];
 366       $check = civicrm_api3($dao->entity_type, 'get', $params);
 367       if ((bool) $check['count']) {
 368         $result = civicrm_api($dao->entity_type, 'delete', $params);
 369         if ($result['is_error']) {
 370           if (isset($dao->name)) {
 371             $params['name'] = $dao->name;
 372           }
 373           $this->onApiError($dao->entity_type, 'delete', $params, $result);
 374         }
 375       }
 376       CRM_Core_DAO::executeQuery('DELETE FROM civicrm_managed WHERE id = %1', [
 377         1 => [$dao->id, 'Integer'],
 378       ]);
 379     }
 380   }
 381
 382   /**
 383    * Get declarations.
 384    *
 385    * @return array|null
 386    */
 387   public function getDeclarations() {
 388     if ($this->declarations === NULL) {
 389       $this->declarations = [];
 390       foreach (CRM_Core_Component::getEnabledComponents() as $component) {
 391         /** @var CRM_Core_Component_Info $component */
 392         $this->declarations = array_merge($this->declarations, $component->getManagedEntities());
 393       }
 394       CRM_Utils_Hook::managed($this->declarations);
 395       $this->declarations = self::cleanDeclarations($this->declarations);
 396     }
 397     return $this->declarations;
 398   }
 399
 400   /**
 401    * @param array $modules
 402    *   Array<CRM_Core_Module>.
 403    *
 404    * @return array
 405    *   indexed by is_active,name
 406    */
 407   protected static function createModuleIndex($modules) {
 408     $result = [];
 409     foreach ($modules as $module) {
 410       $result[$module->is_active][$module->name] = $module;
 411     }
 412     return $result;
 413   }
 414
 415   /**
 416    * @param array $moduleIndex
 417    * @param array $declarations
 418    *
 419    * @return array
 420    *   indexed by module,name
 421    */
 422   protected static function createDeclarationIndex($moduleIndex, $declarations) {
 423     $result = [];
 424     if (!isset($moduleIndex[TRUE])) {
 425       return $result;
 426     }
 427     foreach ($moduleIndex[TRUE] as $moduleName => $module) {
 428       if ($module->is_active) {
 429         // need an empty array() for all active modules, even if there are no current $declarations
 430         $result[$moduleName] = [];
 431       }
 432     }
 433     foreach ($declarations as $declaration) {
 434       $result[$declaration['module']][$declaration['name']] = $declaration;
 435     }
 436     return $result;
 437   }
 438
 439   /**
 440    * @param $declarations
 441    *
 442    * @return string|bool
 443    *   string on error, or FALSE
 444    */
 445   protected static function validate($declarations) {
 446     foreach ($declarations as $declare) {
 447       foreach (['name', 'module', 'entity', 'params'] as $key) {
 448         if (empty($declare[$key])) {
 449           $str = print_r($declare, TRUE);
 450           return ("Managed Entity is missing field \"$key\": $str");
 451         }
 452       }
 453       // FIXME: validate that each 'module' is known
 454     }
 455     return FALSE;
 456   }
 457
 458   /**
 459    * @param array $declarations
 460    *
 461    * @return array
 462    */
 463   protected static function cleanDeclarations($declarations) {
 464     foreach ($declarations as $name => &$declare) {
 465       if (!array_key_exists('name', $declare)) {
 466         $declare['name'] = $name;
 467       }
 468     }
 469     return $declarations;
 470   }
 471
 472   /**
 473    * @param string $entity
 474    * @param string $action
 475    * @param array $params
 476    * @param array $result
 477    *
 478    * @throws Exception
 479    */
 480   protected function onApiError($entity, $action, $params, $result) {
 481     CRM_Core_Error::debug_var('ManagedEntities_failed', [
 482       'entity' => $entity,
 483       'action' => $action,
 484       'params' => $params,
 485       'result' => $result,
 486     ]);
 487     throw new Exception('API error: ' . $result['error_message'] . ' on ' . $entity . '.' . $action
 488       . (!empty($params['name']) ? '( entity name ' . $params['name'] . ')' : '')
 489     );
 490   }
 491
 492   /**
 493    * Determine if an entity supports APIv3-based activation/de-activation.
 494    * @param string $entity_type
 495    *
 496    * @return bool
 497    * @throws \CiviCRM_API3_Exception
 498    */
 499   private function isActivationSupported(string $entity_type): bool {
 500     if (!isset(Civi::$statics[__CLASS__][__FUNCTION__][$entity_type])) {
 501       $actions = civicrm_api3($entity_type, 'getactions', [])['values'];
 502       Civi::$statics[__CLASS__][__FUNCTION__][$entity_type] = FALSE;
 503       if (in_array('create', $actions, TRUE) && in_array('getfields', $actions)) {
 504         $fields = civicrm_api3($entity_type, 'getfields', ['action' => 'create'])['values'];
 505         Civi::$statics[__CLASS__][__FUNCTION__][$entity_type] = array_key_exists('is_active', $fields);
 506       }
 507     }
 508     return Civi::$statics[__CLASS__][__FUNCTION__][$entity_type];
 509   }
 510
 511 }