}
/**
- * @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;
}
/**
- * Read the managed entity
+ * Read a managed entity using APIv3.
*
+ * @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
*/
}
}
+ /**
+ * 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);
$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!
}
/**
- * 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 \CRM_Core_Module $module
* @param array $todos
- * $name => array().
+ * 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();
}
}
+ /**
+ * For all disabled modules, disable any managed entities.
+ */
public function reconcileDisabledModules() {
if (empty($this->moduleIndex[FALSE])) {
return;
}
}
+ /**
+ * 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])) {
}
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();
}
/**
- * Create a new entity
+ * Create a new entity.
*
* @param array $todo
* Entity specification (per hook_civicrm_managedEntities).
}
/**
- * 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;
}
/**
- * @param $modules
+ * @param array $modules
+ * Array<CRM_Core_Module>.
*
* @return array
* indexed by is_active,name
}
/**
- * @param $moduleIndex
- * @param $declarations
+ * @param array $moduleIndex
+ * @param array $declarations
*
* @return array
* indexed by module,name
}
/**
- * This hook is called for declaring managed entities via API
+ * This hook is called for declaring managed entities via API.
*
* @param array $entities
- * List of pending entities.
+ * List of pending entities. Each entity is an array with keys:
+ * + 'module': string; for module-extensions, this is the fully-qualifed name (e.g. "com.example.mymodule"); for CMS modules, the name is prefixed by the CMS (e.g. "drupal.mymodule")
+ * + 'name': string, a symbolic name which can be used to track this entity (Note: Each module creates its own namespace)
+ * + 'entity': string, an entity-type supported by the CiviCRM API (Note: this currently must be an entity which supports the 'is_active' property)
+ * + 'params': array, the entity data as supported by the CiviCRM API
+ * + 'update' (v4.5+): string, a policy which describes when to update records
+ * - 'always' (default): always update the managed-entity record; changes in $entities will override any local changes (eg by the site-admin)
+ * - 'never': never update the managed-entity record; changes made locally (eg by the site-admin) will override changes in $entities
+ * + 'cleanup' (v4.5+): string, a policy which describes whether to cleanup the record when it becomes orphaned (ie when $entities no longer references the record)
+ * - 'always' (default): always delete orphaned records
+ * - 'never': never delete orphaned records
+ * - 'unused': only delete orphaned records if there are no other references to it in the DB. (This is determined by calling the API's "getrefcount" action.)
*
* @return null
* the return value is ignored
projects / civicrm-core.git / commitdiff