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:

1. An .entityType.php file loaded via entity-types-php mixin (recommended for most entities).
2. 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 using hook_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 to entityType.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 zero or more paths, each keyed by the action that the path is used for. The most common actions are 'add', 'view', 'update' and 'delete'. Less common actions include 'browse', 'preview', 'copy' and 'detach'. Paths may include square-bracket tokens such as [id] or [price_set_id].
• '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) e.g 'int', 'int(10) unsigned', 'bigint', 'tinyint', 'varchar(30)', 'datetime', 'decimal'
  • 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 legacy DAO::fields
• 'links_callback' (deprecated): (array[function($class, &$links)] list of callbacks to modify legacy DAO::getReferenceColumns