function entity_crud_hook_entity_info

7.x entity.api.php entity_crud_hook_entity_info()

Provide an entity type via the entity CRUD API.

This is a placeholder for describing further keys for hook_entity_info(), which are introduced the entity API for providing a new entity type with the entity CRUD API. For that the entity API provides two controllers:

  • EntityAPIController: A regular CRUD controller.
  • EntityAPIControllerExportable: Extends the regular controller to additionally support exportable entities and/or entities making use of a name key.

See entity_metadata_hook_entity_info() for the documentation of additional keys for hook_entity_info() as introduced by the entity API and supported for any entity type.

The entity CRUD API supports the following keys:

  • entity class: (optional) A class the controller will use for instantiating entities. It is suggested to make use of the provided "Entity" class or to extend it.
  • bundle of: (optional) Entity types can be used as bundles for other entity types. To enable this functionality, use the 'bundle of' key to indicate which entity type this entity serves as a bundle for. But note that the other entity type will still need to declare entities of this type as bundles, as described by the documentation of hook_entity_info(). If the other entity type is fieldable, the entity API controller takes care of invoking the field API bundle attachers. Note that field_attach_delete_bundle() has to be invoked manually upon module uninstallation. See entity_test_entity_info() and entity_test_uninstall() for examples.
  • module: (optional) The module providing the entity type. This is optional, but strongly suggested.
  • exportable: (optional) Whether the entity is exportable. Defaults to FALSE. If enabled, a name key should be specified and db columns for the module and status key as defined by entity_exportable_schema_fields() have to exist in the entity's base table. Also see 'entity keys' below. This option requires the EntityAPIControllerExportable to work.
  • entity keys: An array of keys as defined by Drupal core. The following additional keys are used by the entity CRUD API:

    • name: (optional) The key of the entity property containing the unique, machine readable name of the entity. If specified, this is used as identifier of the entity, while the usual 'id' key is still required and may be used when modules deal with entities generically, or to refer to the entity internally, i.e. in the database. If a name key is given, the name is used as entity identifier by the entity API module, metadata wrappers and entity-type specific hooks. However note that for consistency all generic entity hooks like hook_entity_load() are invoked with the entities keyed by numeric id, while entity-type specific hooks like hook_{entity_type}_load() are invoked with the entities keyed by name. Also, just as entity_load_single() entity_load() may be called with names passed as the $ids parameter, while the results of entity_load() are always keyed by numeric id. Thus, it is suggested to make use of entity_load_multiple_by_name() to implement entity-type specific loading functions like {entity_type}_load_multiple(), as this function returns the entities keyed by name. See entity_test_get_types() for an example. For exportable entities, it is strongly recommended to make use of a machine name as names are portable across systems. This option requires the EntityAPIControllerExportable to work.
    • module: (optional) A key for the module property used by the entity CRUD API to save the source module name for exportable entities that have been provided in code. Defaults to 'module'.
    • status: (optional) The name of the entity property used by the entity CRUD API to save the exportable entity status using defined bit flags. Defaults to 'status'. See entity_has_status().
    • default revision: (optional) The name of the entity property used by the entity CRUD API to determine if a newly-created revision should be set as the default revision. Defaults to 'default_revision'. Note that on entity insert the created revision will be always default regardless of the value of this entity property.
  • export: (optional) An array of information used for exporting. For ctools exportables compatibility any export-keys supported by ctools may be added to this array too.

    • default hook: What hook to invoke to find exportable entities that are currently defined. This hook is automatically called by the CRUD controller during entity_load(). Defaults to 'default_' . $entity_type.
  • admin ui: (optional) An array of optional information used for providing an administrative user interface. To enable the UI at least the path must be given. Apart from that, the 'access callback' (see below) is required for the entity, as well as the 'ENTITY_TYPE_form' for editing, adding and cloning. The form gets the entity and the operation ('edit', 'add' or 'clone') passed. See entity_ui_get_form() for more details. Known keys are:

    • path: A path where the UI should show up as expected by hook_menu().
    • controller class: (optional) A controller class name for providing the UI. Defaults to EntityDefaultUIController, which implements an admin UI suiting for managing configuration entities. Other provided controllers suiting for content entities are EntityContentUIController or EntityBundleableUIController (which work fine despite the poorly named 'admin ui' key). For customizing the UI inherit from the default class and override methods as suiting and specify your class as controller class.
    • file: (optional) The name of the file in which the entity form resides as it is required by hook_menu().
    • file path: (optional) The path to the file as required by hook_menu. If not set, it defaults to entity type's module's path, thus the entity types 'module' key is required.
    • menu wildcard: The wildcard to use in paths of the hook_menu() items. Defaults to %entity_object which is the loader provided by Entity API.
  • rules controller class: (optional) A controller class for providing Rules integration, or FALSE to disable this feature. The given class has to inherit from the class EntityDefaultRulesController, which serves as default in case the entity type is not marked as configuration. For configuration entities it defaults to FALSE.
  • metadata controller class: (optional) A controller class for providing entity property info. By default some info is generated out of the information provided in your hook_schema() implementation, while only read access is granted to that properties by default. Based upon that the Entity tokens module also generates token replacements for your entity type, once activated. Override the controller class to adapt the defaults and to improve and complete the generated metadata. Set it to FALSE to disable this feature. Defaults to the EntityDefaultMetadataController class.
  • extra fields controller class: (optional) A controller class for providing field API extra fields. Defaults to none. The class must implement the EntityExtraFieldsControllerInterface. Display extra fields that are exposed that way are rendered by default by the EntityAPIController. The EntityDefaultExtraFieldsController class may be used to generate extra fields based upon property metadata, which in turn get rendered by default by the EntityAPIController.
  • features controller class: (optional) A controller class for providing Features module integration for exportable entities. The given class has to inherit from the default class being EntityDefaultFeaturesController. Set it to FALSE to disable this feature.
  • i18n controller class: (optional) A controller class for providing i18n module integration for (exportable) entities. The given class has to inherit from the class EntityDefaultI18nStringController. Defaults to FALSE (disabled). See EntityDefaultI18nStringController for more information.
  • views controller class: (optional) A controller class for providing views integration. The given class has to inherit from the class EntityDefaultViewsController, which is set as default in case the providing module has been specified (see 'module') and the module does not provide any views integration. Else it defaults to FALSE, which disables this feature. See EntityDefaultViewsController.
  • access callback: (optional) Specify a callback that returns access permissions for the operations 'create', 'update', 'delete' and 'view'. The callback gets optionally the entity and the user account to check for passed. See entity_access() for more details on the arguments and entity_metadata_no_hook_node_access() for an example. This is optional, but suggested for the Rules integration, and required for the admin ui (see above).
  • form callback: (optional) Specfiy a callback that returns a fully built edit form for your entity type. See entity_form(). In case the 'admin ui' is used, no callback needs to be specified.
  • entity cache: (optional) Whether entities should be cached using the cache system. Requires the entitycache module to be installed and enabled and the module key to be specified. As cached entities are only retrieved by id key, the cache would not apply to exportable entities retrieved by name key. If enabled and the entitycache module is active, 'field cache' is obsolete and is automatically disabled. Defaults to FALSE.

See also

hook_entity_info()

entity_metadata_hook_entity_info()

File

entity/entity.api.php, line 167
Hooks provided by the entity API.

Code

function entity_crud_hook_entity_info() {
  $return = array(
    'entity_test' => array(
      'label' => t('Test Entity'),
      'entity class' => 'Entity',
      'controller class' => 'EntityAPIController',
      'base table' => 'entity_test',
      'module' => 'entity_test',
      'fieldable' => TRUE,
      'entity keys' => array(
        'id' => 'pid',
        'name' => 'name',
        'bundle' => 'type',
      ),
      'bundles' => array(),
    ),
  );
  foreach (entity_test_get_types() as $name => $info) {
    $return['entity_test']['bundles'][$name] = array(
      'label' => $info['label'],
    );
  }
  return $return;
}