entity.api.php

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