entity.api.php

Hooks provided by the entity API.

Functions

Namesort descending Description
entity_crud_hook_entity_info Provide an entity type via the entity CRUD API.
entity_hook_field_info Provide entity property information for fields.
entity_metadata_hook_entity_info Provide additional metadata for entities.
hook_entity_property_info Allow modules to define metadata about entity properties.
hook_entity_property_info_alter Allow modules to alter metadata about entity properties.
hook_entity_views_field_handlers_alter Alter the handlers used by the data selection tables provided by this module.

File

entity/entity.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the entity API.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Provide an entity type via the entity CRUD API.
  12. *
  13. * This is a placeholder for describing further keys for hook_entity_info(),
  14. * which are introduced the entity API for providing a new entity type with the
  15. * entity CRUD API. For that the entity API provides two controllers:
  16. * - EntityAPIController: A regular CRUD controller.
  17. * - EntityAPIControllerExportable: Extends the regular controller to
  18. * additionally support exportable entities and/or entities making use of a
  19. * name key.
  20. * See entity_metadata_hook_entity_info() for the documentation of additional
  21. * keys for hook_entity_info() as introduced by the entity API and supported for
  22. * any entity type.
  23. *
  24. * The entity CRUD API supports the following keys:
  25. * - entity class: (optional) A class the controller will use for instantiating
  26. * entities. It is suggested to make use of the provided "Entity" class or to
  27. * extend it.
  28. * - bundle of: (optional) Entity types can be used as bundles for
  29. * other entity types. To enable this functionality, use the 'bundle of' key
  30. * to indicate which entity type this entity serves as a bundle for. But note
  31. * that the other entity type will still need to declare entities of this
  32. * type as bundles, as described by the documentation of hook_entity_info().
  33. * If the other entity type is fieldable, the entity API controller takes
  34. * care of invoking the field API bundle attachers. Note that
  35. * field_attach_delete_bundle() has to be invoked manually upon module
  36. * uninstallation. See entity_test_entity_info() and entity_test_uninstall()
  37. * for examples.
  38. * - module: (optional) The module providing the entity type. This is optional,
  39. * but strongly suggested.
  40. * - exportable: (optional) Whether the entity is exportable. Defaults to FALSE.
  41. * If enabled, a name key should be specified and db columns for the module
  42. * and status key as defined by entity_exportable_schema_fields() have to
  43. * exist in the entity's base table. Also see 'entity keys' below.
  44. * This option requires the EntityAPIControllerExportable to work.
  45. * - entity keys: An array of keys as defined by Drupal core. The following
  46. * additional keys are used by the entity CRUD API:
  47. * - name: (optional) The key of the entity property containing the unique,
  48. * machine readable name of the entity. If specified, this is used as
  49. * identifier of the entity, while the usual 'id' key is still required and
  50. * may be used when modules deal with entities generically, or to refer to
  51. * the entity internally, i.e. in the database.
  52. * If a name key is given, the name is used as entity identifier by the
  53. * entity API module, metadata wrappers and entity-type specific hooks.
  54. * However note that for consistency all generic entity hooks like
  55. * hook_entity_load() are invoked with the entities keyed by numeric id,
  56. * while entity-type specific hooks like hook_{entity_type}_load() are
  57. * invoked with the entities keyed by name.
  58. * Also, just as entity_load_single() entity_load() may be called
  59. * with names passed as the $ids parameter, while the results of
  60. * entity_load() are always keyed by numeric id. Thus, it is suggested to
  61. * make use of entity_load_multiple_by_name() to implement entity-type
  62. * specific loading functions like {entity_type}_load_multiple(), as this
  63. * function returns the entities keyed by name. See entity_test_get_types()
  64. * for an example.
  65. * For exportable entities, it is strongly recommended to make use of a
  66. * machine name as names are portable across systems.
  67. * This option requires the EntityAPIControllerExportable to work.
  68. * - module: (optional) A key for the module property used by the entity CRUD
  69. * API to save the source module name for exportable entities that have been
  70. * provided in code. Defaults to 'module'.
  71. * - status: (optional) The name of the entity property used by the entity
  72. * CRUD API to save the exportable entity status using defined bit flags.
  73. * Defaults to 'status'. See entity_has_status().
  74. * - default revision: (optional) The name of the entity property used by
  75. * the entity CRUD API to determine if a newly-created revision should be
  76. * set as the default revision. Defaults to 'default_revision'.
  77. * Note that on entity insert the created revision will be always default
  78. * regardless of the value of this entity property.
  79. * - export: (optional) An array of information used for exporting. For ctools
  80. * exportables compatibility any export-keys supported by ctools may be added
  81. * to this array too.
  82. * - default hook: What hook to invoke to find exportable entities that are
  83. * currently defined. This hook is automatically called by the CRUD
  84. * controller during entity_load(). Defaults to 'default_' . $entity_type.
  85. * - admin ui: (optional) An array of optional information used for providing an
  86. * administrative user interface. To enable the UI at least the path must be
  87. * given. Apart from that, the 'access callback' (see below) is required for
  88. * the entity, as well as the 'ENTITY_TYPE_form' for editing, adding and
  89. * cloning. The form gets the entity and the operation ('edit', 'add' or
  90. * 'clone') passed. See entity_ui_get_form() for more details.
  91. * Known keys are:
  92. * - path: A path where the UI should show up as expected by hook_menu().
  93. * - controller class: (optional) A controller class name for providing the
  94. * UI. Defaults to EntityDefaultUIController, which implements an admin UI
  95. * suiting for managing configuration entities. Other provided controllers
  96. * suiting for content entities are EntityContentUIController or
  97. * EntityBundleableUIController (which work fine despite the poorly named
  98. * 'admin ui' key).
  99. * For customizing the UI inherit from the default class and override
  100. * methods as suiting and specify your class as controller class.
  101. * - file: (optional) The name of the file in which the entity form resides
  102. * as it is required by hook_menu().
  103. * - file path: (optional) The path to the file as required by hook_menu. If
  104. * not set, it defaults to entity type's module's path, thus the entity
  105. * types 'module' key is required.
  106. * - menu wildcard: The wildcard to use in paths of the hook_menu() items.
  107. * Defaults to %entity_object which is the loader provided by Entity API.
  108. * - rules controller class: (optional) A controller class for providing Rules
  109. * integration, or FALSE to disable this feature. The given class has to
  110. * inherit from the class EntityDefaultRulesController, which serves as
  111. * default in case the entity type is not marked as configuration. For
  112. * configuration entities it defaults to FALSE.
  113. * - metadata controller class: (optional) A controller class for providing
  114. * entity property info. By default some info is generated out of the
  115. * information provided in your hook_schema() implementation, while only read
  116. * access is granted to that properties by default. Based upon that the
  117. * Entity tokens module also generates token replacements for your entity
  118. * type, once activated.
  119. * Override the controller class to adapt the defaults and to improve and
  120. * complete the generated metadata. Set it to FALSE to disable this feature.
  121. * Defaults to the EntityDefaultMetadataController class.
  122. * - extra fields controller class: (optional) A controller class for providing
  123. * field API extra fields. Defaults to none.
  124. * The class must implement the EntityExtraFieldsControllerInterface. Display
  125. * extra fields that are exposed that way are rendered by default by the
  126. * EntityAPIController. The EntityDefaultExtraFieldsController class may be
  127. * used to generate extra fields based upon property metadata, which in turn
  128. * get rendered by default by the EntityAPIController.
  129. * - features controller class: (optional) A controller class for providing
  130. * Features module integration for exportable entities. The given class has to
  131. * inherit from the default class being EntityDefaultFeaturesController. Set
  132. * it to FALSE to disable this feature.
  133. * - i18n controller class: (optional) A controller class for providing
  134. * i18n module integration for (exportable) entities. The given class has to
  135. * inherit from the class EntityDefaultI18nStringController. Defaults to
  136. * FALSE (disabled). See EntityDefaultI18nStringController for more
  137. * information.
  138. * - views controller class: (optional) A controller class for providing views
  139. * integration. The given class has to inherit from the class
  140. * EntityDefaultViewsController, which is set as default in case the providing
  141. * module has been specified (see 'module') and the module does not provide
  142. * any views integration. Else it defaults to FALSE, which disables this
  143. * feature. See EntityDefaultViewsController.
  144. * - access callback: (optional) Specify a callback that returns access
  145. * permissions for the operations 'create', 'update', 'delete' and 'view'.
  146. * The callback gets optionally the entity and the user account to check for
  147. * passed. See entity_access() for more details on the arguments and
  148. * entity_metadata_no_hook_node_access() for an example.
  149. * This is optional, but suggested for the Rules integration, and required for
  150. * the admin ui (see above).
  151. * - form callback: (optional) Specfiy a callback that returns a fully built
  152. * edit form for your entity type. See entity_form().
  153. * In case the 'admin ui' is used, no callback needs to be specified.
  154. * - entity cache: (optional) Whether entities should be cached using the cache
  155. * system. Requires the entitycache module to be installed and enabled and the
  156. * module key to be specified. As cached entities are only retrieved by id key,
  157. * the cache would not apply to exportable entities retrieved by name key.
  158. * If enabled and the entitycache module is active, 'field cache' is obsolete
  159. * and is automatically disabled. Defaults to FALSE.
  160. *
  161. * @see hook_entity_info()
  162. * @see entity_metadata_hook_entity_info()
  163. */
  164. function entity_crud_hook_entity_info() {
  165. $return = array(
  166. 'entity_test' => array(
  167. 'label' => t('Test Entity'),
  168. 'entity class' => 'Entity',
  169. 'controller class' => 'EntityAPIController',
  170. 'base table' => 'entity_test',
  171. 'module' => 'entity_test',
  172. 'fieldable' => TRUE,
  173. 'entity keys' => array(
  174. 'id' => 'pid',
  175. 'name' => 'name',
  176. 'bundle' => 'type',
  177. ),
  178. 'bundles' => array(),
  179. ),
  180. );
  181. foreach (entity_test_get_types() as $name => $info) {
  182. $return['entity_test']['bundles'][$name] = array(
  183. 'label' => $info['label'],
  184. );
  185. }
  186. return $return;
  187. }
  188. /**
  189. * Provide additional metadata for entities.
  190. *
  191. * This is a placeholder for describing further keys for hook_entity_info(),
  192. * which are introduced the entity API in order to support any entity type; e.g.
  193. * to make entity_save(), entity_create(), entity_view() and others work.
  194. * See entity_crud_hook_entity_info() for the documentation of additional keys
  195. * for hook_entity_info() as introduced by the entity API for providing new
  196. * entity types with the entity CRUD API.
  197. *
  198. * Additional keys are:
  199. * - plural label: (optional) The human-readable, plural name of the entity
  200. * type. As 'label' it should start capitalized.
  201. * - description: (optional) A human-readable description of the entity type.
  202. * - access callback: (optional) Specify a callback that returns access
  203. * permissions for the operations 'create', 'update', 'delete' and 'view'.
  204. * The callback gets optionally the entity and the user account to check for
  205. * passed. See entity_access() for more details on the arguments and
  206. * entity_metadata_no_hook_node_access() for an example.
  207. * - creation callback: (optional) A callback that creates a new instance of
  208. * this entity type. See entity_metadata_create_node() for an example.
  209. * - save callback: (optional) A callback that permanently saves an entity of
  210. * this type.
  211. * - deletion callback: (optional) A callback that permanently deletes an
  212. * entity of this type.
  213. * - revision deletion callback: (optional) A callback that deletes a revision
  214. * of the entity.
  215. * - view callback: (optional) A callback to render a list of entities.
  216. * See entity_metadata_view_node() as example.
  217. * - form callback: (optional) A callback that returns a fully built edit form
  218. * for the entity type.
  219. * - token type: (optional) A type name to use for token replacements. Set it
  220. * to FALSE if there aren't any token replacements for this entity type.
  221. * - configuration: (optional) A boolean value that specifies whether the entity
  222. * type should be considered as configuration. Modules working with entities
  223. * may use this value to decide whether they should deal with a certain entity
  224. * type. Defaults to TRUE to for entity types that are exportable, else to
  225. * FALSE.
  226. *
  227. * @see hook_entity_info()
  228. * @see entity_crud_hook_entity_info()
  229. * @see entity_access()
  230. * @see entity_create()
  231. * @see entity_save()
  232. * @see entity_delete()
  233. * @see entity_view()
  234. * @see entity_form()
  235. */
  236. function entity_metadata_hook_entity_info() {
  237. return array(
  238. 'node' => array(
  239. 'label' => t('Node'),
  240. 'access callback' => 'entity_metadata_no_hook_node_access',
  241. // ...
  242. ),
  243. );
  244. }
  245. /**
  246. * Allow modules to define metadata about entity properties.
  247. *
  248. * Modules providing properties for any entities defined in hook_entity_info()
  249. * can implement this hook to provide metadata about this properties.
  250. * For making use of the metadata have a look at the provided wrappers returned
  251. * by entity_metadata_wrapper().
  252. * For providing property information for fields see entity_hook_field_info().
  253. *
  254. * @return
  255. * An array whose keys are entity type names and whose values are arrays
  256. * containing the keys:
  257. * - properties: The array describing all properties for this entity. Entries
  258. * are keyed by the property name and contain an array of metadata for each
  259. * property. The name may only contain alphanumeric lowercase characters
  260. * and underscores. Known keys are:
  261. * - label: A human readable, translated label for the property.
  262. * - description: (optional) A human readable, translated description for
  263. * the property.
  264. * - type: The data type of the property. To make the property actually
  265. * useful it is important to map your properties to one of the known data
  266. * types, which currently are:
  267. * - text: Any text.
  268. * - token: A string containing only lowercase letters, numbers, and
  269. * underscores starting with a letter; e.g. this type is useful for
  270. * machine readable names.
  271. * - integer: A usual PHP integer value.
  272. * - decimal: A PHP float or integer.
  273. * - date: A full date and time, as timestamp.
  274. * - duration: A duration as number of seconds.
  275. * - boolean: A usual PHP boolean value.
  276. * - uri: An absolute URI or URL.
  277. * - entities - You may use the type of each entity known by
  278. * hook_entity_info(), e.g. 'node' or 'user'. Internally entities are
  279. * represented by their identifieres. In case of single-valued
  280. * properties getter callbacks may return full entity objects as well,
  281. * while a value of FALSE is interpreted like a NULL value as "property
  282. * is not set".
  283. * - entity: A special type to be used generically for entities where the
  284. * entity type is not known beforehand. The entity has to be
  285. * represented using an EntityMetadataWrapper.
  286. * - struct: This as well as any else not known type may be used for
  287. * supporting arbitrary data structures. For that additional metadata
  288. * has to be specified with the 'property info' key. New type names
  289. * have to be properly prefixed with the module name.
  290. * - list: A list of values, represented as numerically indexed array.
  291. * The list<TYPE> notation may be used to specify the type of the
  292. * contained items, where TYPE may be any valid type expression.
  293. * - bundle: (optional) If the property is an entity, you may specify the
  294. * bundle of the referenced entity.
  295. * - options list: (optional) A callback that returns a list of possible
  296. * values for the property. The callback has to return an array as
  297. * used by hook_options_list().
  298. * Note that it is possible to return a different set of options depending
  299. * whether they are used in read or in write context. See
  300. * EntityMetadataWrapper::optionsList() for more details on that.
  301. * - getter callback: (optional) A callback used to retrieve the value of
  302. * the property. Defaults to entity_property_verbatim_get().
  303. * It is important that your data is represented, as documented for your
  304. * data type, e.g. a date has to be a timestamp. Thus if necessary, the
  305. * getter callback has to do the necessary conversion. In case of an empty
  306. * or not set value, the callback has to return NULL.
  307. * - setter callback: (optional) A callback used to set the value of the
  308. * property. In many cases entity_property_verbatim_set() can be used.
  309. * - validation callback: (optional) A callback that returns whether the
  310. * passed data value is valid for the property. May be used to implement
  311. * additional validation checks, such as to ensure the value is a valid
  312. * mail address.
  313. * - access callback: (optional) An access callback to allow for checking
  314. * 'view' and 'edit' access for the described property. If no callback
  315. * is specified, a 'setter permission' may be specified instead.
  316. * - setter permission: (optional) A permission that describes whether
  317. * a user has permission to set ('edit') this property. This permission
  318. * is only be taken into account, if no 'access callback' is given.
  319. * - schema field: (optional) In case the property is directly based upon
  320. * a field specified in the entity's hook_schema(), the name of the field.
  321. * - queryable: (optional) Whether a property is queryable with
  322. * EntityFieldQuery. Defaults to TRUE if a 'schema field' is specified, or
  323. * if the deprecated 'query callback' is set to
  324. * 'entity_metadata_field_query'. Otherwise it defaults to FALSE.
  325. * - query callback: (deprecated) A callback for querying for entities
  326. * having the given property value. See entity_property_query().
  327. * Generally, properties should be queryable via EntityFieldQuery. If
  328. * that is the case, just set 'queryable' to TRUE.
  329. * - required: (optional) Whether this property is required for the creation
  330. * of a new instance of its entity. See
  331. * entity_property_values_create_entity().
  332. * - field: (optional) A boolean indicating whether a property is stemming
  333. * from a field.
  334. * - computed: (optional) A boolean indicating whether a property is
  335. * computed, i.e. the property value is not stored or loaded by the
  336. * entity's controller but determined on the fly by the getter callback.
  337. * Defaults to FALSE.
  338. * - entity views field: (optional) If enabled, the property is
  339. * automatically exposed as views field available to all views query
  340. * backends listing this entity-type. As the property value will always be
  341. * generated from a loaded entity object, this is particularly useful for
  342. * 'computed' properties. Defaults to FALSE.
  343. * - sanitized: (optional) For textual properties only, whether the text is
  344. * already sanitized. In this case you might want to also specify a raw
  345. * getter callback. Defaults to FALSE.
  346. * - sanitize: (optional) For textual properties, that are not sanitized
  347. * yet, specify a function for sanitizing the value. Defaults to
  348. * check_plain().
  349. * - raw getter callback: (optional) For sanitized textual properties, a
  350. * separate callback which can be used to retrieve the raw, unprocessed
  351. * value.
  352. * - clear: (optional) An array of property names, of which the cache should
  353. * be cleared too once this property is updated. As a rule of thumb any
  354. * duplicated properties should be avoided though.
  355. * - property info: (optional) An array of info for an arbitrary data
  356. * structure together with any else not defined type, see data type
  357. * 'struct'. Specify metadata in the same way as defined for this hook.
  358. * - property info alter: (optional) A callback for altering the property
  359. * info before it is used by the metadata wrappers.
  360. * - property defaults: (optional) An array of property info defaults for
  361. * each property derived of the wrapped data item (e.g. an entity).
  362. * Applied by the metadata wrappers.
  363. * - auto creation: (optional) Properties of type 'struct' may specify
  364. * this callback which is used to automatically create the data structure
  365. * (e.g. an array) if necessary. This is necessary in order to support
  366. * setting a property of a not yet initialized data structure.
  367. * See entity_metadata_field_file_callback() for an example.
  368. * - translatable: (optional) Whether the property is translatable, defaults
  369. * to FALSE.
  370. * - entity token: (optional) If Entity tokens module is enabled, the
  371. * module provides a token for the property if one does not exist yet.
  372. * Specify FALSE to disable this functionality for the property.
  373. * - bundles: An array keyed by bundle name containing further metadata
  374. * related to the bundles only. This array may contain the key 'properties'
  375. * with an array of info about the bundle specific properties, structured in
  376. * the same way as the entity properties array.
  377. *
  378. * @see hook_entity_property_info_alter()
  379. * @see entity_get_property_info()
  380. * @see entity_metadata_wrapper()
  381. */
  382. function hook_entity_property_info() {
  383. $info = array();
  384. $properties = &$info['node']['properties'];
  385. $properties['nid'] = array(
  386. 'label' => t("Content ID"),
  387. 'type' => 'integer',
  388. 'description' => t("The unique content ID."),
  389. );
  390. return $info;
  391. }
  392. /**
  393. * Allow modules to alter metadata about entity properties.
  394. *
  395. * @see hook_entity_property_info()
  396. */
  397. function hook_entity_property_info_alter(&$info) {
  398. $properties = &$info['node']['bundles']['poll']['properties'];
  399. $properties['poll-votes'] = array(
  400. 'label' => t("Poll votes"),
  401. 'description' => t("The number of votes that have been cast on a poll node."),
  402. 'type' => 'integer',
  403. 'getter callback' => 'entity_property_poll_node_get_properties',
  404. );
  405. }
  406. /**
  407. * Provide entity property information for fields.
  408. *
  409. * This is a placeholder for describing further keys for hook_field_info(),
  410. * which are introduced by the entity API.
  411. *
  412. * For providing entity property info for fields each field type may specify a
  413. * property type to map to using the key 'property_type'. With that info in
  414. * place useful defaults are generated, which suffice for a lot of field
  415. * types.
  416. * However it is possible to specify further callbacks that may alter the
  417. * generated property info. To do so use the key 'property_callbacks' and set
  418. * it to an array of function names. Apart from that any property info provided
  419. * for a field instance using the key 'property info' is added in too.
  420. *
  421. * @see entity_field_info_alter()
  422. * @see entity_metadata_field_text_property_callback()
  423. */
  424. function entity_hook_field_info() {
  425. return array(
  426. 'text' => array(
  427. 'label' => t('Text'),
  428. 'property_type' => 'text',
  429. // ...
  430. ),
  431. );
  432. }
  433. /**
  434. * Alter the handlers used by the data selection tables provided by this module.
  435. *
  436. * @param array $field_handlers
  437. * An array of the field handler classes to use for specific types. The keys
  438. * are the types, mapped to their respective classes. Contained types are:
  439. * - All primitive types known by the entity API (see
  440. * hook_entity_property_info()).
  441. * - options: Special type for fields having an options list.
  442. * - field: Special type for Field API fields.
  443. * - entity: Special type for entity-valued fields.
  444. * - relationship: Views relationship handler to use for relationships.
  445. * Values for all specific entity types can be additionally added.
  446. *
  447. * @see entity_views_field_definition()
  448. * @see entity_views_get_field_handlers()
  449. */
  450. function hook_entity_views_field_handlers_alter(array &$field_handlers) {
  451. $field_handlers['duration'] = 'example_duration_handler';
  452. $field_handlers['node'] = 'example_node_handler';
  453. }
  454. /**
  455. * @} End of "addtogroup hooks".
  456. */