6 * The ManagedEntities system allows modules to add records to the database
7 * declaratively. Those records will be automatically inserted, updated,
8 * deactivated, and deleted in tandem with their modules.
10 class CRM_Core_ManagedEntities
{
13 * Get clean up options.
17 public static function getCleanupOptions() {
19 'always' => ts('Always'),
20 'never' => ts('Never'),
21 'unused' => ts('If Unused'),
27 * Array($status => array($name => CRM_Core_Module)).
29 protected $moduleIndex;
32 * Actions arising from the managed entities.
36 protected $managedActions = [];
40 * List of all entity declarations.
41 * @see CRM_Utils_Hook::managed()
43 protected $declarations;
48 * @return \CRM_Core_ManagedEntities
50 public static function singleton($fresh = FALSE) {
52 if ($fresh ||
!$singleton) {
53 $singleton = new CRM_Core_ManagedEntities(CRM_Core_Module
::getAll());
59 * Perform an asynchronous reconciliation when the transaction ends.
61 public static function scheduleReconciliation() {
62 CRM_Core_Transaction
::addCallback(
63 CRM_Core_Transaction
::PHASE_POST_COMMIT
,
65 CRM_Core_ManagedEntities
::singleton(TRUE)->reconcile();
68 'ManagedEntities::reconcile'
73 * @param array $modules
76 public function __construct(array $modules) {
77 $this->moduleIndex
= $this->createModuleIndex($modules);
81 * Read a managed entity using APIv3.
85 * @param string $moduleName
86 * The name of the module which declared entity.
88 * The symbolic name of the entity.
90 * API representation, or NULL if the entity does not exist
92 public function get($moduleName, $name) {
93 $dao = new CRM_Core_DAO_Managed();
94 $dao->module
= $moduleName;
96 if ($dao->find(TRUE)) {
98 'id' => $dao->entity_id
,
102 $result = civicrm_api3($dao->entity_type
, 'getsingle', $params);
104 catch (Exception
$e) {
105 $this->onApiError($dao->entity_type
, 'getsingle', $params, $result);
115 * Identify any enabled/disabled modules. Add new entities, update
116 * existing entities, and remove orphaned (stale) entities.
118 * @param bool $ignoreUpgradeMode
120 * @throws \CRM_Core_Exception
122 public function reconcile($ignoreUpgradeMode = FALSE) {
123 // Do not reconcile whilst we are in upgrade mode
124 if (CRM_Core_Config
::singleton()->isUpgradeMode() && !$ignoreUpgradeMode) {
127 $this->loadDeclarations();
128 if ($error = $this->validate($this->getDeclarations())) {
129 throw new CRM_Core_Exception($error);
131 $this->loadManagedEntityActions();
132 $this->reconcileEnabledModules();
133 $this->reconcileDisabledModules();
134 $this->reconcileUnknownModules();
138 * Force-revert a record back to its original state.
139 * @param array $params
140 * Key->value properties of CRM_Core_DAO_Managed used to match an existing record
142 public function revert(array $params) {
143 $mgd = new \
CRM_Core_DAO_Managed();
144 $mgd->copyValues($params);
146 $this->loadDeclarations();
147 $declarations = CRM_Utils_Array
::findAll($this->declarations
, [
148 'module' => $mgd->module
,
149 'name' => $mgd->name
,
150 'entity' => $mgd->entity_type
,
152 if ($mgd->id
&& isset($declarations[0])) {
153 $this->updateExistingEntity($mgd, ['update' => 'always'] +
$declarations[0]);
160 * For all enabled modules, add new entities, update
161 * existing entities, and remove orphaned (stale) entities.
163 protected function reconcileEnabledModules(): void
{
164 // Note: any thing currently declared is necessarily from
165 // an active module -- because we got it from a hook!
167 // index by moduleName,name
168 $decls = $this->createDeclarationIndex($this->moduleIndex
, $this->getDeclarations());
169 foreach ($decls as $moduleName => $todos) {
170 if ($this->isModuleEnabled($moduleName)) {
171 $this->reconcileEnabledModule($moduleName);
177 * For one enabled module, add new entities, update existing entities,
178 * and remove orphaned (stale) entities.
180 * @param string $module
182 protected function reconcileEnabledModule(string $module): void
{
183 foreach ($this->getManagedEntitiesToUpdate(['module' => $module]) as $todo) {
184 $dao = new CRM_Core_DAO_Managed();
185 $dao->module
= $todo['module'];
186 $dao->name
= $todo['name'];
187 $dao->entity_type
= $todo['entity_type'];
188 $dao->entity_id
= $todo['entity_id'];
189 $dao->entity_modified_date
= $todo['entity_modified_date'];
190 $dao->id
= $todo['id'];
191 $this->updateExistingEntity($dao, $todo);
194 foreach ($this->getManagedEntitiesToDelete(['module' => $module]) as $todo) {
195 $dao = new CRM_Core_DAO_Managed();
196 $dao->module
= $todo['module'];
197 $dao->name
= $todo['name'];
198 $dao->entity_type
= $todo['entity_type'];
199 $dao->id
= $todo['id'];
200 $dao->cleanup
= $todo['cleanup'];
201 $dao->entity_id
= $todo['entity_id'];
202 $this->removeStaleEntity($dao);
204 foreach ($this->getManagedEntitiesToCreate(['module' => $module]) as $todo) {
205 $this->insertNewEntity($todo);
210 * Get the managed entities to be created.
212 * @param array $filters
216 protected function getManagedEntitiesToCreate(array $filters = []): array {
217 return $this->getManagedEntities(array_merge($filters, ['managed_action' => 'create']));
221 * Get the managed entities to be updated.
223 * @param array $filters
227 protected function getManagedEntitiesToUpdate(array $filters = []): array {
228 return $this->getManagedEntities(array_merge($filters, ['managed_action' => 'update']));
232 * Get the managed entities to be deleted.
234 * @param array $filters
238 protected function getManagedEntitiesToDelete(array $filters = []): array {
239 // Return array in reverse-order so that child entities are cleaned up before their parents
240 return array_reverse($this->getManagedEntities(array_merge($filters, ['managed_action' => 'delete'])));
244 * Get the managed entities that fit the criteria.
246 * @param array $filters
250 protected function getManagedEntities(array $filters = []): array {
252 foreach ($this->managedActions
as $actionKey => $action) {
253 foreach ($filters as $filterKey => $filterValue) {
254 if ($action[$filterKey] !== $filterValue) {
258 $return[$actionKey] = $action;
264 * For all disabled modules, disable any managed entities.
266 protected function reconcileDisabledModules() {
267 if (empty($this->moduleIndex
[FALSE])) {
271 $in = CRM_Core_DAO
::escapeStrings(array_keys($this->moduleIndex
[FALSE]));
272 $dao = new CRM_Core_DAO_Managed();
273 $dao->whereAdd("module in ($in)");
274 $dao->orderBy('id DESC');
276 while ($dao->fetch()) {
277 $this->disableEntity($dao);
283 * Remove any orphaned (stale) entities that are linked to
286 protected function reconcileUnknownModules() {
288 if (array_key_exists(0, $this->moduleIndex
) && is_array($this->moduleIndex
[0])) {
289 $knownModules = array_merge($knownModules, array_keys($this->moduleIndex
[0]));
291 if (array_key_exists(1, $this->moduleIndex
) && is_array($this->moduleIndex
[1])) {
292 $knownModules = array_merge($knownModules, array_keys($this->moduleIndex
[1]));
295 $dao = new CRM_Core_DAO_Managed();
296 if (!empty($knownModules)) {
297 $in = CRM_Core_DAO
::escapeStrings($knownModules);
298 $dao->whereAdd("module NOT IN ($in)");
299 $dao->orderBy('id DESC');
302 while ($dao->fetch()) {
303 $this->removeStaleEntity($dao);
308 * Create a new entity.
311 * Entity specification (per hook_civicrm_managedEntities).
313 protected function insertNewEntity($todo) {
314 if ($todo['params']['version'] == 4) {
315 $todo['params']['checkPermissions'] = FALSE;
318 $result = civicrm_api($todo['entity_type'], 'create', ['debug' => TRUE] +
$todo['params']);
319 if (!empty($result['is_error'])) {
320 $this->onApiError($todo['entity_type'], 'create', $todo['params'], $result);
323 $dao = new CRM_Core_DAO_Managed();
324 $dao->module
= $todo['module'];
325 $dao->name
= $todo['name'];
326 $dao->entity_type
= $todo['entity_type'];
327 // A fatal error will result if there is no valid id but if
328 // this is v4 api we might need to access it via ->first().
329 $dao->entity_id
= $result['id'] ??
$result->first()['id'];
330 $dao->cleanup
= $todo['cleanup'] ??
NULL;
335 * Update an entity which is believed to exist.
337 * @param CRM_Core_DAO_Managed $dao
339 * Entity specification (per hook_civicrm_managedEntities).
341 protected function updateExistingEntity($dao, $todo) {
342 $policy = $todo['update'] ??
'always';
343 $doUpdate = ($policy === 'always');
345 if ($policy === 'unmodified') {
346 // If this is not an APIv4 managed entity, the entity_modidfied_date will always be null
347 if (!CRM_Core_BAO_Managed
::isApi4ManagedType($dao->entity_type
)) {
348 Civi
::log()->warning('ManagedEntity update policy "unmodified" specified for entity type ' . $dao->entity_type
. ' which is not an APIv4 ManagedEntity. Falling back to policy "always".');
350 $doUpdate = empty($dao->entity_modified_date
);
353 if ($doUpdate && $todo['params']['version'] == 3) {
354 $defaults = ['id' => $dao->entity_id
];
355 if ($this->isActivationSupported($dao->entity_type
)) {
356 $defaults['is_active'] = 1;
358 $params = array_merge($defaults, $todo['params']);
360 $manager = CRM_Extension_System
::singleton()->getManager();
361 if ($dao->entity_type
=== 'Job' && !$manager->extensionIsBeingInstalledOrEnabled($dao->module
)) {
362 // Special treatment for scheduled jobs:
364 // If we're being called as part of enabling/installing a module then
365 // we want the default behaviour of setting is_active = 1.
367 // However, if we're just being called by a normal cache flush then we
368 // should not re-enable a job that an administrator has decided to disable.
370 // Without this logic there was a problem: site admin might disable
371 // a job, but then when there was a flush op, the job was re-enabled
372 // which can cause significant embarrassment, depending on the job
373 // ("Don't worry, sending mailings is disabled right now...").
374 unset($params['is_active']);
377 $result = civicrm_api($dao->entity_type
, 'create', $params);
378 if ($result['is_error']) {
379 $this->onApiError($dao->entity_type
, 'create', $params, $result);
382 elseif ($doUpdate && $todo['params']['version'] == 4) {
383 $params = ['checkPermissions' => FALSE] +
$todo['params'];
384 $params['values']['id'] = $dao->entity_id
;
385 civicrm_api4($dao->entity_type
, 'update', $params);
388 if (isset($todo['cleanup']) ||
$doUpdate) {
389 $dao->cleanup
= $todo['cleanup'] ??
NULL;
390 // Reset the `entity_modified_date` timestamp if reverting record.
391 $dao->entity_modified_date
= $doUpdate ?
'null' : NULL;
397 * Update an entity which (a) is believed to exist and which (b) ought to be
400 * @param CRM_Core_DAO_Managed $dao
402 * @throws \CiviCRM_API3_Exception
404 protected function disableEntity($dao): void
{
405 $entity_type = $dao->entity_type
;
406 if ($this->isActivationSupported($entity_type)) {
407 // FIXME cascading for payproc types?
410 'id' => $dao->entity_id
,
413 $result = civicrm_api($dao->entity_type
, 'create', $params);
414 if ($result['is_error']) {
415 $this->onApiError($dao->entity_type
, 'create', $params, $result);
417 // Reset the `entity_modified_date` timestamp to indicate that the entity has not been modified by the user.
418 $dao->entity_modified_date
= 'null';
424 * Remove a stale entity (if policy allows).
426 * @param CRM_Core_DAO_Managed $dao
427 * @throws CRM_Core_Exception
429 protected function removeStaleEntity($dao) {
430 $policy = empty($dao->cleanup
) ?
'always' : $dao->cleanup
;
441 if (CRM_Core_BAO_Managed
::isApi4ManagedType($dao->entity_type
)) {
442 $getRefCount = \Civi\Api4\Utils\CoreUtil
::getRefCount($dao->entity_type
, $dao->entity_id
);
445 $getRefCount = civicrm_api3($dao->entity_type
, 'getrefcount', [
446 'id' => $dao->entity_id
,
450 // FIXME: This extra counting should be unnecessary, because getRefCount only returns values if count > 0
452 foreach ($getRefCount as $refCount) {
453 $total +
= $refCount['count'];
456 $doDelete = ($total == 0);
460 throw new CRM_Core_Exception('Unrecognized cleanup policy: ' . $policy);
463 // APIv4 delete - deletion from `civicrm_managed` will be taken care of by
464 // CRM_Core_BAO_Managed::on_hook_civicrm_post()
465 if ($doDelete && CRM_Core_BAO_Managed
::isApi4ManagedType($dao->entity_type
)) {
466 civicrm_api4($dao->entity_type
, 'delete', [
467 'checkPermissions' => FALSE,
468 'where' => [['id', '=', $dao->entity_id
]],
475 'id' => $dao->entity_id
,
477 $check = civicrm_api3($dao->entity_type
, 'get', $params);
478 if ($check['count']) {
479 $result = civicrm_api($dao->entity_type
, 'delete', $params);
480 if ($result['is_error']) {
481 if (isset($dao->name
)) {
482 $params['name'] = $dao->name
;
484 $this->onApiError($dao->entity_type
, 'delete', $params, $result);
487 CRM_Core_DAO
::executeQuery('DELETE FROM civicrm_managed WHERE id = %1', [
488 1 => [$dao->id
, 'Integer'],
498 protected function getDeclarations() {
499 return $this->declarations
;
503 * @param array $modules
504 * Array<CRM_Core_Module>.
507 * indexed by is_active,name
509 protected function createModuleIndex($modules) {
511 foreach ($modules as $module) {
512 $result[$module->is_active
][$module->name
] = $module;
518 * @param array $moduleIndex
519 * @param array $declarations
522 * indexed by module,name
524 protected function createDeclarationIndex($moduleIndex, $declarations) {
526 if (!isset($moduleIndex[TRUE])) {
529 foreach ($moduleIndex[TRUE] as $moduleName => $module) {
530 if ($module->is_active
) {
531 // need an empty array() for all active modules, even if there are no current $declarations
532 $result[$moduleName] = [];
535 foreach ($declarations as $declaration) {
536 $result[$declaration['module']][$declaration['name']] = $declaration;
542 * @param array $declarations
544 * @return string|bool
545 * string on error, or FALSE
547 protected function validate($declarations) {
548 foreach ($declarations as $module => $declare) {
549 foreach (['name', 'module', 'entity', 'params'] as $key) {
550 if (empty($declare[$key])) {
551 $str = print_r($declare, TRUE);
552 return ts('Managed Entity (%1) is missing field "%2": %3', [$module, $key, $str]);
555 if (!$this->isModuleRecognised($declare['module'])) {
556 return ts('Entity declaration references invalid or inactive module name [%1]', [$declare['module']]);
563 * Is the module recognised (as an enabled or disabled extension in the system).
565 * @param string $module
569 protected function isModuleRecognised(string $module): bool {
570 return $this->isModuleDisabled($module) ||
$this->isModuleEnabled($module);
574 * Is the module enabled.
576 * @param string $module
580 protected function isModuleEnabled(string $module): bool {
581 return isset($this->moduleIndex
[TRUE][$module]);
585 * Is the module disabled.
587 * @param string $module
591 protected function isModuleDisabled(string $module): bool {
592 return isset($this->moduleIndex
[FALSE][$module]);
596 * @param array $declarations
600 protected function cleanDeclarations(array $declarations): array {
601 foreach ($declarations as $name => &$declare) {
602 if (!array_key_exists('name', $declare)) {
603 $declare['name'] = $name;
606 return $declarations;
610 * @param string $entity
611 * @param string $action
612 * @param array $params
613 * @param array $result
617 protected function onApiError($entity, $action, $params, $result) {
618 CRM_Core_Error
::debug_var('ManagedEntities_failed', [
624 throw new Exception('API error: ' . $result['error_message'] . ' on ' . $entity . '.' . $action
625 . (!empty($params['name']) ?
'( entity name ' . $params['name'] . ')' : '')
630 * Determine if an entity supports APIv3-based activation/de-activation.
631 * @param string $entity_type
634 * @throws \CiviCRM_API3_Exception
636 private function isActivationSupported(string $entity_type): bool {
637 if (!isset(Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type])) {
638 $actions = civicrm_api3($entity_type, 'getactions', [])['values'];
639 Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type] = FALSE;
640 if (in_array('create', $actions, TRUE) && in_array('getfields', $actions)) {
641 $fields = civicrm_api3($entity_type, 'getfields', ['action' => 'create'])['values'];
642 Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type] = array_key_exists('is_active', $fields);
645 return Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type];
649 * Load declarations into the class property.
651 * This picks it up from hooks and enabled components.
653 protected function loadDeclarations(): void
{
654 $this->declarations
= [];
655 foreach (CRM_Core_Component
::getEnabledComponents() as $component) {
656 $this->declarations
= array_merge($this->declarations
, $component->getManagedEntities());
658 CRM_Utils_Hook
::managed($this->declarations
);
659 $this->declarations
= $this->cleanDeclarations($this->declarations
);
662 protected function loadManagedEntityActions(): void
{
663 $managedEntities = Managed
::get(FALSE)->addSelect('*')->execute();
664 foreach ($managedEntities as $managedEntity) {
665 $key = "{$managedEntity['module']}_{$managedEntity['name']}_{$managedEntity['entity_type']}";
666 // Set to 'delete' - it will be overwritten below if it is to be updated.
668 $this->managedActions
[$key] = array_merge($managedEntity, ['managed_action' => $action]);
670 foreach ($this->declarations
as $declaration) {
671 $key = "{$declaration['module']}_{$declaration['name']}_{$declaration['entity']}";
672 if (isset($this->managedActions
[$key])) {
673 $this->managedActions
[$key]['params'] = $declaration['params'];
674 $this->managedActions
[$key]['managed_action'] = 'update';
675 $this->managedActions
[$key]['cleanup'] = $declaration['cleanup'] ??
NULL;
676 $this->managedActions
[$key]['update'] = $declaration['update'] ??
'always';
679 $this->managedActions
[$key] = [
680 'module' => $declaration['module'],
681 'name' => $declaration['name'],
682 'entity_type' => $declaration['entity'],
683 'managed_action' => 'create',
684 'params' => $declaration['params'],
685 'cleanup' => $declaration['cleanup'] ??
NULL,
686 'update' => $declaration['update'] ??
'always',