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.
8 class CRM_Core_ManagedEntities
{
11 * Get clean up options.
15 public static function getCleanupOptions() {
17 'always' => ts('Always'),
18 'never' => ts('Never'),
19 'unused' => ts('If Unused'),
25 * Array($status => array($name => CRM_Core_Module)).
27 protected $moduleIndex;
31 * List of all entity declarations.
32 * @see CRM_Utils_Hook::managed()
34 protected $declarations;
39 * @return \CRM_Core_ManagedEntities
41 public static function singleton($fresh = FALSE) {
43 if ($fresh ||
!$singleton) {
44 $singleton = new CRM_Core_ManagedEntities(CRM_Core_Module
::getAll(), NULL);
50 * Perform an asynchronous reconciliation when the transaction ends.
52 public static function scheduleReconciliation() {
53 CRM_Core_Transaction
::addCallback(
54 CRM_Core_Transaction
::PHASE_POST_COMMIT
,
56 CRM_Core_ManagedEntities
::singleton(TRUE)->reconcile();
59 'ManagedEntities::reconcile'
64 * @param array $modules
66 * @param array $declarations
67 * Per hook_civicrm_managed.
69 public function __construct($modules, $declarations) {
70 $this->moduleIndex
= self
::createModuleIndex($modules);
72 if ($declarations !== NULL) {
73 $this->declarations
= self
::cleanDeclarations($declarations);
76 $this->declarations
= NULL;
81 * Read a managed entity using APIv3.
83 * @param string $moduleName
84 * The name of the module which declared entity.
86 * The symbolic name of the entity.
88 * API representation, or NULL if the entity does not exist
90 public function get($moduleName, $name) {
91 $dao = new CRM_Core_DAO_Managed();
92 $dao->module
= $moduleName;
94 if ($dao->find(TRUE)) {
96 'id' => $dao->entity_id
,
100 $result = civicrm_api3($dao->entity_type
, 'getsingle', $params);
102 catch (Exception
$e) {
103 $this->onApiError($dao->entity_type
, 'getsingle', $params, $result);
113 * Identify any enabled/disabled modules. Add new entities, update
114 * existing entities, and remove orphaned (stale) entities.
115 * @param bool $ignoreUpgradeMode
119 public function reconcile($ignoreUpgradeMode = FALSE) {
120 // Do not reconcile whilst we are in upgrade mode
121 if (CRM_Core_Config
::singleton()->isUpgradeMode() && !$ignoreUpgradeMode) {
124 if ($error = $this->validate($this->getDeclarations())) {
125 throw new Exception($error);
127 $this->reconcileEnabledModules();
128 $this->reconcileDisabledModules();
129 $this->reconcileUnknownModules();
133 * For all enabled modules, add new entities, update
134 * existing entities, and remove orphaned (stale) entities.
138 public function reconcileEnabledModules() {
139 // Note: any thing currently declared is necessarily from
140 // an active module -- because we got it from a hook!
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);
148 elseif (isset($this->moduleIndex
[FALSE][$moduleName])) {
149 // do nothing -- module should get swept up later
152 throw new Exception("Entity declaration references invalid or inactive module name [$moduleName]");
158 * For one enabled module, add new entities, update existing entities,
159 * and remove orphaned (stale) entities.
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).
166 public function reconcileEnabledModule(CRM_Core_Module
$module, $todos) {
167 $dao = new CRM_Core_DAO_Managed();
168 $dao->module
= $module->name
;
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
]);
177 // remove stale entity; not in $todos
178 $this->removeStaleEntity($dao);
182 // create new entities from leftover $todos
183 foreach ($todos as $name => $todo) {
184 $this->insertNewEntity($todo);
189 * For all disabled modules, disable any managed entities.
191 public function reconcileDisabledModules() {
192 if (empty($this->moduleIndex
[FALSE])) {
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');
201 while ($dao->fetch()) {
202 $this->disableEntity($dao);
208 * Remove any orphaned (stale) entities that are linked to
211 public function reconcileUnknownModules() {
213 if (array_key_exists(0, $this->moduleIndex
) && is_array($this->moduleIndex
[0])) {
214 $knownModules = array_merge($knownModules, array_keys($this->moduleIndex
[0]));
216 if (array_key_exists(1, $this->moduleIndex
) && is_array($this->moduleIndex
[1])) {
217 $knownModules = array_merge($knownModules, array_keys($this->moduleIndex
[1]));
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');
227 while ($dao->fetch()) {
228 $this->removeStaleEntity($dao);
233 * Create a new entity.
236 * Entity specification (per hook_civicrm_managedEntities).
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);
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;
256 * Update an entity which is believed to exist.
258 * @param CRM_Core_DAO_Managed $dao
260 * Entity specification (per hook_civicrm_managedEntities).
262 public function updateExistingEntity($dao, $todo) {
263 $policy = CRM_Utils_Array
::value('update', $todo, 'always');
264 $doUpdate = ($policy === 'always');
267 $defaults = ['id' => $dao->entity_id
];
268 if ($this->isActivationSupported($dao->entity_type
)) {
269 $defaults['is_active'] = 1;
271 $params = array_merge($defaults, $todo['params']);
273 $manager = CRM_Extension_System
::singleton()->getManager();
274 if ($dao->entity_type
=== 'Job' && !$manager->extensionIsBeingInstalledOrEnabled($dao->module
)) {
275 // Special treatment for scheduled jobs:
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.
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.
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']);
290 $result = civicrm_api($dao->entity_type
, 'create', $params);
291 if ($result['is_error']) {
292 $this->onApiError($dao->entity_type
, 'create', $params, $result);
296 if (isset($todo['cleanup'])) {
297 $dao->cleanup
= $todo['cleanup'];
303 * Update an entity which (a) is believed to exist and which (b) ought to be
306 * @param CRM_Core_DAO_Managed $dao
308 * @throws \CiviCRM_API3_Exception
310 public function disableEntity($dao): void
{
311 $entity_type = $dao->entity_type
;
312 if ($this->isActivationSupported($entity_type)) {
313 // FIXME cascading for payproc types?
316 'id' => $dao->entity_id
,
319 $result = civicrm_api($dao->entity_type
, 'create', $params);
320 if ($result['is_error']) {
321 $this->onApiError($dao->entity_type
, 'create', $params, $result);
327 * Remove a stale entity (if policy allows).
329 * @param CRM_Core_DAO_Managed $dao
332 public function removeStaleEntity($dao) {
333 $policy = empty($dao->cleanup
) ?
'always' : $dao->cleanup
;
344 $getRefCount = civicrm_api3($dao->entity_type
, 'getrefcount', [
346 'id' => $dao->entity_id
,
350 foreach ($getRefCount['values'] as $refCount) {
351 $total +
= $refCount['count'];
354 $doDelete = ($total == 0);
358 throw new \
Exception('Unrecognized cleanup policy: ' . $policy);
364 'id' => $dao->entity_id
,
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 $this->onApiError($dao->entity_type
, 'delete', $params, $result);
373 CRM_Core_DAO
::executeQuery('DELETE FROM civicrm_managed WHERE id = %1', [
374 1 => [$dao->id
, 'Integer'],
384 public function getDeclarations() {
385 if ($this->declarations
=== NULL) {
386 $this->declarations
= [];
387 foreach (CRM_Core_Component
::getEnabledComponents() as $component) {
388 /** @var CRM_Core_Component_Info $component */
389 $this->declarations
= array_merge($this->declarations
, $component->getManagedEntities());
391 CRM_Utils_Hook
::managed($this->declarations
);
392 $this->declarations
= self
::cleanDeclarations($this->declarations
);
394 return $this->declarations
;
398 * @param array $modules
399 * Array<CRM_Core_Module>.
402 * indexed by is_active,name
404 protected static function createModuleIndex($modules) {
406 foreach ($modules as $module) {
407 $result[$module->is_active
][$module->name
] = $module;
413 * @param array $moduleIndex
414 * @param array $declarations
417 * indexed by module,name
419 protected static function createDeclarationIndex($moduleIndex, $declarations) {
421 if (!isset($moduleIndex[TRUE])) {
424 foreach ($moduleIndex[TRUE] as $moduleName => $module) {
425 if ($module->is_active
) {
426 // need an empty array() for all active modules, even if there are no current $declarations
427 $result[$moduleName] = [];
430 foreach ($declarations as $declaration) {
431 $result[$declaration['module']][$declaration['name']] = $declaration;
437 * @param $declarations
439 * @return string|bool
440 * string on error, or FALSE
442 protected static function validate($declarations) {
443 foreach ($declarations as $declare) {
444 foreach (['name', 'module', 'entity', 'params'] as $key) {
445 if (empty($declare[$key])) {
446 $str = print_r($declare, TRUE);
447 return ("Managed Entity is missing field \"$key\": $str");
450 // FIXME: validate that each 'module' is known
456 * @param array $declarations
460 protected static function cleanDeclarations($declarations) {
461 foreach ($declarations as $name => &$declare) {
462 if (!array_key_exists('name', $declare)) {
463 $declare['name'] = $name;
466 return $declarations;
470 * @param string $entity
471 * @param string $action
472 * @param array $params
473 * @param array $result
477 protected function onApiError($entity, $action, $params, $result) {
478 CRM_Core_Error
::debug_var('ManagedEntities_failed', [
484 throw new Exception('API error: ' . $result['error_message'] . ' on ' . $entity . '.' . $action
485 . !empty($params['name']) ?
'( entity name ' . $params['name'] . ')' : ''
490 * Determine if an entity supports APIv3-based activation/de-activation.
491 * @param string $entity_type
494 * @throws \CiviCRM_API3_Exception
496 private function isActivationSupported(string $entity_type): bool {
497 if (!isset(Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type])) {
498 $actions = civicrm_api3($entity_type, 'getactions', [])['values'];
499 Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type] = FALSE;
500 if (in_array('create', $actions, TRUE) && in_array('getfields', $actions)) {
501 $fields = civicrm_api3($entity_type, 'getfields', ['action' => 'create'])['values'];
502 Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type] = array_key_exists('is_active', $fields);
505 return Civi
::$statics[__CLASS__
][__FUNCTION__
][$entity_type];