CiviCRM Entities¶
An "entity" in CiviCRM is a persistent object (typically a sql table), with the following properties:
- A database table: In most cases, there is a 1-to-1 relationship between entities and tables.
- Or other storage medium: Some entities are stored elsewhere, for example Afforms are stored as files.
- Fields: Typically the columns of the database table, although extra fields (e.g. a read-only calculated value) are supported by APIv4.
- An API: Most entities have a corresponding api for CRUD, metadata and other actions.
Tools¶
- Boilerplate code for a new entityType can be generated with
civix generate:entity
. - Most entities are exposed to the CiviCRM API and can be browsed with the API Explorer
- Some Entity-Relationship Diagrams are available to help with better understanding the CiviCRM database design.
Declaration¶
Every entity in CiviCRM is declared via either:
- An
.entityType.php
file loaded viaentity-types-php
mixin (recommended for most entities). - Or
hook_civicrm_entityTypes
(advanced use, for dynamic or generated entities, e.g. ECK).
Note: at the lowest level, hook_civicrm_entityTypes
is the only way for extensions to declare entities.
But the extension mixin entity-types-php
typically handles this automatically; it finds and loads all
.entityType.php
files and passes their contents to the hook.
If you have an advanced use-case and need to implement hook_civicrm_entityTypes
yourself, the data you
pass to the hook will be an array in the same format as that of an .entityType.php
file described below, keyed by the name of the entity, plus the extra key 'module` which must contain the full_name of your extension.
Definition¶
The entityType definition array can contain the following keys:
*
Denotes a required value
'name*'
(string
) - unique entity name, capitalized CamelCase (e.g."SearchDisplay"
)'module*'
(string
) - name of extension declaring the entity (only required when usinghook_civicrm_entityTypes
, the mixin passes this automatically)'table'
(string|null
) - a SQL table name (e.g."civicrm_search_display"
) (required for all entities with a sql table)'class'
(string|null
) - a PHP DAO class (e.g."CRM_Search_DAO_SearchDisplay"
) - used for backward compatibility when converting existing entities from xml/dao toentityType.php
'getInfo'
(callback():array
) - Function returning entity metadata such as:title
(ts(string)
)title_plural
(ts(string)
)description
(ts(string)
)log
(boolean
)add
(string
)icon
(string
)label_field
(string
)
'getPaths'
(callback():array
) - Function returning an array of paths at which this entity can be created, viewed, updated & deleted'getIndices'
(callback():array
) - Function returning an array of sql indices.'getFields'
(callback():array
) - Function returning an array of field definitions, keyed by field name, with possible values:title
(ts(string)
)description
(ts(string)
)sql_type
(string
)input_type
(string
)data_type
(string
)required
(boolean
)localizable
(boolean
)serialize
(int
)default
(mixed
)usage
(array
)input_attrs
(array
)pseudoconstant
(array
)permission
(array
)
'fields_callback'
(deprecated) (array[function($class, &$fields)]
) list of callbacks to modify legacyDAO::fields
'links_callback'
(deprecated): (array[function($class, &$links)]
list of callbacks to modify legacyDAO::getReferenceColumns