diff --git a/core/includes/entity.api.php b/core/includes/entity.api.php index 58d7f8a..193fbe2 100644 --- a/core/includes/entity.api.php +++ b/core/includes/entity.api.php @@ -11,7 +11,7 @@ */ /** - * Alter the entity info. + * Alter the entity type definition. * * Modules may implement this hook to alter the information that defines an * entity. All properties that are available in @@ -19,13 +19,14 @@ * * In addition, the following properties should be added here: * - bundles: An array describing all bundles for this object type. Keys are - * bundles machine names, as found in the objects' 'bundle' property - * (defined in the 'entity_keys' entry above). Elements: + * bundle machine names, as found in the objects' 'bundle' property + * (defined in the 'entity_keys' entry for the entity type in the + * EntityManager). Elements: * - label: The human-readable name of the bundle. - * - uri_callback: Same as the 'uri_callback' key documented above for the - * entity type, but for the bundle only. When determining the URI of an - * entity, if a 'uri_callback' is defined for both the entity type and - * the bundle, the one for the bundle is used. + * - uri_callback: The same as the 'uri_callback' key defined for the entity + * type in the EntityManager, but for the bundle only. When determining + * the URI of an entity, if a 'uri_callback' is defined for both the + * entity type and the bundle, the one for the bundle is used. * - admin: An array of information that allows Field UI pages to attach * themselves to the existing administration pages for the bundle. * Elements: @@ -53,7 +54,7 @@ * view mode, thus reducing the amount of display configurations to keep * track of. Keys of the array are view mode names. Each view mode is * described by an array with the following key/value pairs: - * - label: The human-readable name of the view mode + * - label: The human-readable name of the view mode. * - custom settings: A boolean specifying whether the view mode should by * default use its own custom field display settings. If FALSE, entities * displayed in this view mode will reuse the 'default' display settings @@ -61,10 +62,16 @@ * enabled), but administrators can later use the Field UI to apply custom * display settings specific to the view mode. * - * @param $entity_info - * The entity info array, keyed by entity name. + * @param array $entity_info + * An associative array of all entity type definitions, keyed by the entity + * type name. * + * @see \Drupal\Core\Entity\Entity * @see Drupal\Core\Plugin\Type\EntityManager + * @see entity_get_info() + * + * @todo Allow a module to add its bundles and view modes before other modules + * alter the definition. */ function hook_entity_info_alter(&$entity_info) { // Set the controller class for nodes to an alternate implementation of the diff --git a/core/includes/entity.inc b/core/includes/entity.inc index ea94640..87d7424 100644 --- a/core/includes/entity.inc +++ b/core/includes/entity.inc @@ -13,13 +13,19 @@ use Drupal\Core\Entity\EntityInterface; /** - * Gets the entity info array of an entity type. + * Gets the entity definition for an entity type. * - * @param $entity_type - * The entity type, e.g. node, for which the info shall be returned, or NULL - * to return an array with info about all types. + * @param string|null $entity_type + * (optional) The entity type (e.g. 'node'). Leave NULL to retrieve + * information for all entity types. * - * @see Drupal\Core\Plugin\Type\EntityManager + * @return array + * An array containing the entity type's definition, as retrieved with + * \Drupal\Core\Plugin\Type\EntityManager. If $entity_type is NULL, an + * associative array of all entity type definitions keyed by entity type is + * returned. + * + * @see \Drupal\Core\Plugin\Type\EntityManager * @see hook_entity_info_alter() */ function entity_get_info($entity_type = NULL) { diff --git a/core/lib/Drupal/Core/Plugin/Type/EntityManager.php b/core/lib/Drupal/Core/Plugin/Type/EntityManager.php index 6481cb8..cdc8ac8 100644 --- a/core/lib/Drupal/Core/Plugin/Type/EntityManager.php +++ b/core/lib/Drupal/Core/Plugin/Type/EntityManager.php @@ -2,7 +2,7 @@ /** * @file - * Contains Drupal\Core\Plugin\Type\EntityManager. + * Contains \Drupal\Core\Plugin\Type\EntityManager. */ namespace Drupal\Core\Plugin\Type; @@ -14,96 +14,104 @@ use Drupal\Core\Cache\CacheBackendInterface; /** - * Inform the base system and the Field API about one or more entity types. + * Manages entity type plugin definitions. * - * Inform the system about one or more entity types (i.e., object types that - * can be loaded via entity_load() and, optionally, to which fields can be - * attached). + * Each entity type definition array is set in the entity type plugin's + * annotation and altered by hook_entity_info_alter(). The definition includes + * the following keys: + * - module: The name of the module providing the type. + * - class: The name of the entity type class. Defaults to + * Drupal\Core\Entity\Entity. + * - base_table: The name of the entity type's base table. Used by + * Drupal\Core\Entity\DatabaseStorageController. + * - controller_class: The name of the class that is used to load the objects. + * The class must implement + * Drupal\Core\Entity\EntityStorageControllerInterface. Defaults to + * Drupal\Core\Entity\DatabaseStorageController. + * - fieldable: (optional) Boolean indicating whether fields can be attached + * to entities of this type. Defaults to FALSE. + * - field_cache: (optional) Boolean indicating whether the Field API's + * Field API's persistent cache of field data should be used. The persistent + * cache should usually only be disabled if a higher level persistent cache + * is available for the entity type. Defaults to TRUE. + * - form_controller_class: (optional) An associative array where the keys + * are the names of the different form operations (such as 'create', + * 'edit', or 'delete') and the values are the names of the controller + * classes for those operations. The name of the operation is passed also + * to the form controller's constructor, so that one class can be used for + * multiple entity forms when the forms are similar. Defaults to + * Drupal\Core\Entity\EntityFormController. + * - label: The human-readable name of the type. + * - label_callback: (optional) A function taking an entity and optional + * langcode argument, and returning the label of the entity. If langcode is + * omitted, the entity's default language is used. + * The entity label is the main string associated with an entity; for + * example, the title of a node or the subject of a comment. If there is an + * entity object property that defines the label, use the 'label' element + * of the 'entity_keys' return value component to provide this information + * (see below). If more complex logic is needed to determine the label of + * an entity, you can instead specify a callback function here, which will + * be called to determine the entity label. See also the + * Drupal\Core\Entity\Entity::label() method, which implements this logic. + * - list_controller_class: (optional) The name of the class that provides + * listings of the The class must implement + * Drupal\Core\Entity\EntityListControllerInterface. Defaults to + * Drupal\Core\Entity\EntityListController. + * - render_controller_class: The name of the class that is used to render the + * entities. Defaults to Drupal\Core\Entity\EntityRenderController. + * - static_cache: (optional) Boolean indicating whether entities should be + * statically cached during a page request. Used by + * Drupal\Core\Entity\DatabaseStorageController. Defaults to TRUE. + * - translation: (optional) An associative array of modules registered as + * field translation handlers. Array keys are the module names, and array + * values can be any data structure the module uses to provide field + * translation. If the value is empty, the module will not be used as a + * translation handler. + * - entity_keys: An array describing how the Field API can extract certain + * information from objects of this entity type. Elements: + * - id: The name of the property that contains the primary ID of the + * entity. Every entity object passed to the Field API must have this + * property and its value must be numeric. + * - revision: (optional) The name of the property that contains the + * revision ID of the entity. The Field API assumes that all revision IDs + * are unique across all entities of a type. This entry can be omitted if + * the entities of this type are not versionable. + * - bundle: (optional) The name of the property that contains the bundle + * name for the entity. The bundle name defines which set of fields are + * attached to the entity (e.g. what nodes call "content type"). This + * entry can be omitted if this entity type exposes a single bundle (such + * that all entities have the same collection of fields). The name of + * this single bundle will be the same as the entity type. + * - label: The name of the property that contains the entity label. For + * example, if the entity's label is located in $entity->subject, then + * 'subject' should be specified here. If complex logic is required to + * build the label, a 'label_callback' should be defined instead (see + * the 'label_callback' section above for details). + * - uuid (optional): The name of the property that contains the universally + * unique identifier of the entity, which is used to distinctly identify + * an entity across different systems. + * - bundle_keys: An array describing how the Field API can extract the + * information it needs from the bundle objects for this type (e.g + * Vocabulary objects for terms; not applicable for nodes). This entry can + * be omitted if this type's bundles do not exist as standalone objects. + * Elements: + * - bundle: The name of the property that contains the name of the bundle + * object. * - * @return - * An array whose keys are entity type names and whose values identify - * properties of those types that the system needs to know about: - * - label: The human-readable name of the type. - * - module: The name of the module providing the type. - * - controller_class: The name of the class that is used to load the objects. - * The class has to implement the - * Drupal\Core\Entity\EntityStorageControllerInterface interface. Leave blank - * to use the Drupal\Core\Entity\DatabaseStorageController implementation. - * - render_controller_class: The name of the class that is used to render - * the entities. Deafaults to Drupal\Core\Entity\EntityRenderController. - * - form_controller_class: An associative array where the keys are the names - * of the different form operations (such as creation, editing or deletion) - * and the values are the names of the controller classes. To facilitate - * supporting the case where an entity form varies only slightly between - * different operations, the name of the operation is passed also to the - * constructor of the form controller class. This way, one class can be used - * for multiple entity forms. - * - list_controller_class: The name of the class that is used to provide - * listings of the entity. The class must implement - * Drupal\Core\Entity\EntityListControllerInterface. Defaults to - * Drupal\Core\Entity\EntityListController. - * - base_table: (used by Drupal\Core\Entity\DatabaseStorageController) The - * name of the entity type's base table. - * - static_cache: (used by Drupal\Core\Entity\DatabaseStorageController) - * FALSE to disable static caching of entities during a page request. - * Defaults to TRUE. - * - field_cache: (used by Field API loading and saving of field data) FALSE - * to disable Field API's persistent cache of field data. Only recommended - * if a higher level persistent cache is available for the entity type. - * Defaults to TRUE. - * - uri_callback: A function taking an entity as argument and returning the - * URI elements of the entity, e.g. 'path' and 'options'. The actual entity - * URI can be constructed by passing these elements to url(). - * - label_callback: (optional) A function taking an entity and optional - * langcode argument, and returning the label of the entity. If langcode is - * omitted, the entity's default language is used. - * The entity label is the main string associated with an entity; for - * example, the title of a node or the subject of a comment. If there is an - * entity object property that defines the label, use the 'label' element - * of the 'entity_keys' return value component to provide this information - * (see below). If more complex logic is needed to determine the label of - * an entity, you can instead specify a callback function here, which will - * be called to determine the entity label. See also the - * Drupal\Core\Entity\Entity::label() method, which implements this logic. - * - fieldable: Set to TRUE if you want your entity type to be fieldable. - * - translation: An associative array of modules registered as field - * translation handlers. Array keys are the module names, array values - * can be any data structure the module uses to provide field translation. - * Any empty value disallows the module to appear as a translation handler. - * - entity_keys: An array describing how the Field API can extract the - * information it needs from the objects of the type. Elements: - * - id: The name of the property that contains the primary id of the - * entity. Every entity object passed to the Field API must have this - * property and its value must be numeric. - * - revision: The name of the property that contains the revision id of - * the entity. The Field API assumes that all revision ids are unique - * across all entities of a type. This entry can be omitted if the - * entities of this type are not versionable. - * - bundle: The name of the property that contains the bundle name for the - * entity. The bundle name defines which set of fields are attached to - * the entity (e.g. what nodes call "content type"). This entry can be - * omitted if this entity type exposes a single bundle (all entities have - * the same collection of fields). The name of this single bundle will be - * the same as the entity type. - * - label: The name of the property that contains the entity label. For - * example, if the entity's label is located in $entity->subject, then - * 'subject' should be specified here. If complex logic is required to - * build the label, a 'label_callback' should be defined instead (see - * the 'label_callback' section above for details). - * - uuid (optional): The name of the property that contains the universally - * unique identifier of the entity, which is used to distinctly identify - * an entity across different systems. - * - bundle_keys: An array describing how the Field API can extract the - * information it needs from the bundle objects for this type (e.g - * $vocabulary objects for terms; not applicable for nodes). This entry can - * be omitted if this type's bundles do not exist as standalone objects. - * Elements: - * - bundle: The name of the property that contains the name of the bundle - * object. + * The defaults for the plugin definition are provided in + * \Drupal\Core\Plugin\Type\EntityManager::definition. * - * @see entity_load() - * @see entity_load_multiple() + * Additional keys may be added to the entity definition with + * hook_entity_info_alter(). In particular, lists of the entity type's bundles + * and view modes are added there. See hook_entity_info_alter() for more + * information. + * + * @see \Drupal\Core\Entity\Entity + * @see entity_get_info() * @see hook_entity_info_alter() + * + * @todo Allow a module to add its bundles and view modes before other modules + * alter the definition. */ class EntityManager extends PluginManagerBase { @@ -136,35 +144,43 @@ class EntityManager extends PluginManagerBase { protected $cacheTags = array('entity_info' => TRUE); /** + * The default values for optional keys of the entity plugin definition. + * + * @var array + */ + protected $defaults = array( + 'class' => 'Drupal\Core\Entity\Entity', + 'controller_class' => 'Drupal\Core\Entity\DatabaseStorageController', + 'entity_keys' => array( + 'revision' => '', + 'bundle' => '', + ), + 'fieldable' => FALSE, + 'field_cache' => TRUE, + 'form_controller_class' => array( + 'default' => 'Drupal\Core\Entity\EntityFormController', + ), + 'list_controller_class' => 'Drupal\Core\Entity\EntityListController', + 'render_controller_class' => 'Drupal\Core\Entity\EntityRenderController', + 'static_cache' => TRUE, + 'translation' => array(), + // Bundles and view modes are added in hook_entity_info_alter(), but we + // provide empty lists of them by default. + 'bundles' => array(), + 'view_modes' => array(), + ); + + /** * Constructs a new Entity plugin manager. */ public function __construct() { + // Allow the plugin definition to be altered by hook_entity_info_alter(). $this->discovery = new AlterDecorator(new AnnotatedClassDiscovery('Core', 'Entity'), 'entity_info'); $this->factory = new DefaultFactory($this); // Entity type plugins includes translated strings, so each language is // cached separately. $this->cacheKey .= ':' . language(LANGUAGE_TYPE_INTERFACE)->langcode; - - $this->defaults = array( - 'class' => 'Drupal\Core\Entity\Entity', - 'controller_class' => 'Drupal\Core\Entity\DatabaseStorageController', - 'list_controller_class' => 'Drupal\Core\Entity\EntityListController', - 'render_controller_class' => 'Drupal\Core\Entity\EntityRenderController', - 'form_controller_class' => array( - 'default' => 'Drupal\Core\Entity\EntityFormController', - ), - 'fieldable' => FALSE, - 'static_cache' => TRUE, - 'field_cache' => TRUE, - 'bundles' => array(), - 'view_modes' => array(), - 'entity_keys' => array( - 'revision' => '', - 'bundle' => '', - ), - 'translation' => array(), - ); } /** diff --git a/core/modules/field/field.attach.inc b/core/modules/field/field.attach.inc index bbb82fe..c972299 100644 --- a/core/modules/field/field.attach.inc +++ b/core/modules/field/field.attach.inc @@ -66,13 +66,17 @@ * * The Field Attach API uses the concept of bundles: the set of fields for a * given entity is defined on a per-bundle basis. The collection of bundles for - * an entity type is defined its hook_entity_info_alter() implementation. For - * instance, node_entity_info() exposes each node type as its own bundle. This - * means that the set of fields of a node is determined by the node type. The - * Field API reads the bundle name for a given entity from a particular property - * of the entity object, and hook_entity_info_alter() defines which property to - * use. For instance, node_entity_info_alter() specifies: - * @code $info['entity_keys']['bundle'] = 'type'@endcode + * an entity type is added to the entity definition with + * hook_entity_info_alter(). For instance, node_entity_info_alter() exposes + * each node type as its own bundle. This means that the set of fields of a + * node is determined by the node type. + * + * The Field API reads the bundle name for a given entity from a particular + * property of the entity object, and hook_entity_info_alter() defines which + * property to use. For instance, node_entity_info_alter() specifies: + * @code + * $info['entity_keys']['bundle'] = 'type' + * @endcode * This indicates that for a particular node object, the bundle name can be * found in $node->type. This property can be omitted if the entity type only * exposes a single bundle (all entities of this type have the same collection diff --git a/core/modules/system/tests/modules/entity_cache_test_dependency/lib/Drupal/entity_cache_test_dependency/Plugin/Core/Entity/EntityCacheTest.php b/core/modules/system/tests/modules/entity_cache_test_dependency/lib/Drupal/entity_cache_test_dependency/Plugin/Core/Entity/EntityCacheTest.php index 1f6d8dc..c0fbea4 100644 --- a/core/modules/system/tests/modules/entity_cache_test_dependency/lib/Drupal/entity_cache_test_dependency/Plugin/Core/Entity/EntityCacheTest.php +++ b/core/modules/system/tests/modules/entity_cache_test_dependency/lib/Drupal/entity_cache_test_dependency/Plugin/Core/Entity/EntityCacheTest.php @@ -2,7 +2,7 @@ /** * @file - * Definition of Drupal\entity_cache_test_dependency\Plugin\Core\Entity\EntityCacheTest. + * Contains Drupal\entity_cache_test_dependency\Plugin\Core\Entity\EntityCacheTest. */ namespace Drupal\entity_cache_test_dependency\Plugin\Core\Entity; @@ -11,7 +11,7 @@ use Drupal\Core\Annotation\Plugin; /** - * Defines the node entity class. + * Defines the EntityCacheTest class. * * @Plugin( * id = "entity_cache_test", diff --git a/core/modules/views/lib/Drupal/views/Tests/ModuleTest.php b/core/modules/views/lib/Drupal/views/Tests/ModuleTest.php index 9a9082c..5bf1574 100644 --- a/core/modules/views/lib/Drupal/views/Tests/ModuleTest.php +++ b/core/modules/views/lib/Drupal/views/Tests/ModuleTest.php @@ -196,8 +196,8 @@ function testStatusFunctions() { * Helper to return an expected views option array. * * @param array $views - * An array of Drupal\views\Plugin\Core\Entity\View objects to create an options array - * for. + * An array of Drupal\views\Plugin\Core\Entity\View objects for which to + * create an options array. * * @return array * A formatted options array that matches the expected output.