hook_civicrm_managed¶
Summary¶
This hook allows a module to declare a list of managed entities using the API.
Notes¶
A managed entity will be automatically inserted, updated, deactivated, and deleted in tandem with enabling, disabling, and uninstalling the module. The hook is called periodically during cache-clear operations.
It is more common to declare 'mgd' (managed) files that are automatically picked up than to leverage this hook directly
Managed Entity Approach: *.mgd.php When the civix code-generator creates a new module, it adds code to ensure any *.mgd.php files are automatically added to hook_civicrm_managed. Consequently, you don't need to put all declarations in one file -- you can find a more convenient place to put them. For example, you might wish to create a folder 'Managed' holding a file per created entity. Or you might prefer in some cases to put the *.mgd.php in the folder of the entity it manages.
For more background, see API and the Art of Installation.
Definition¶
hook_civicrm_managed(&$entities)
Parameters¶
-
array
$entities
- the list of entity declarations; each declaration is an array with these following keys:-
string
module
- for module-extensions, this is the fully-qualifed name (e.g.com.example.mymodule
); for Drupal modules, the name is prefixed bydrupal
(e.g.drupal.mymodule
) -
string
name
- a symbolic name which can be used to track this entity (Note: Each module creates its own namespace) -
string
entity
- an entity-type supported by the CiviCRM API (Note: this currently must be an entity which supports the 'is_active' property) -
array
params
- the entity data as supported by the CiviCRM API -
string
update
- a policy which describes when to update recordsalways
(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
-
string
cleanup
- a policy which describes whether to cleanup the record when it becomes orphaned (i.e. when $entities no longer references the record)always
(default): always delete orphaned recordsnever
: never delete orphaned recordsunused
: only delete orphaned records if there are no other references to it in the DB. (This is determined by calling the API'sgetrefcount
action.)
-
Returns¶
- void - the return value is ignored
Example¶
/**
* Declare a report-template which should be activated whenever this module is enabled
*/
function modulename_civicrm_managed(&$entities) {
$entities[] = array(
'module' => 'com.example.modulename',
'name' => 'myreport',
'entity' => 'ReportTemplate',
'params' => array(
'version' => 3,
'label' => 'Example Report',
'description' => 'Longish description of the example report',
'class_name' => 'CRM_Modulename_Report_Form_Sybunt',
'report_url' => 'mymodule/mysbunt',
'component' => 'CiviContribute',
),
);
}