Skip to content

Managed APIv4 Entities

Basics

Managed Entities are used to package configuration data with extensions. For example, menu items, custom fields or option values all might be needed for the extension to function.

Documentation on creating managed records for use with extensions is in the Extensions - Managed Entities chapter.

ManagedEntity Trait

In order to be managed, the API entity class must use the ManagedEntity trait. This adds the following api actions:

  • revert: update the entity back to its original state as declared by the .mgd.php file or hook_civicrm_managed data.

  • export: outputs configuration data for this and all linked entities, suitable for placing in a .mgd.php file. This api is called by the civix export command.

Lifecycle

Managed entities are declared via hook_civicrm_managed, although it is more typical for extensions to use .mgd.php files which are automatically loaded via mixin.

Once installed, Managed instances are tracked in a table in CiviCRM called civicrm_managed. You can use Civi\Api4\Managed::get() to see what is in there (or make sure your entity has been added) and use the APIv4 reconcile action to have the list of declared entities compared against what is present in the civicrm_managed table - any that are missing will be created and depending on your update mode and cleanup mode they may be updated or deleted if the declaration has changed. Note that you can declare Managed Entities using APIv4 or APIv3 but APIv4 is more robust as it can handle the situation where a similar record already exists.