3 namespace Drupal\Core\Entity;
5 use Drupal\Component\Plugin\Definition\PluginDefinitionInterface;
8 * Provides an interface for an entity type and its metadata.
10 * Additional information can be provided by modules: hook_entity_type_build() can be
11 * implemented to define new properties, while hook_entity_type_alter() can be
12 * implemented to alter existing data and fill-in defaults. Module-specific
13 * properties should be documented in the hook implementations defining them.
15 interface EntityTypeInterface extends PluginDefinitionInterface {
18 * The maximum length of ID, in characters.
20 const ID_MAX_LENGTH = 32;
23 * The maximum length of bundle name, in characters.
25 const BUNDLE_MAX_LENGTH = 32;
28 * Gets any arbitrary property.
30 * @param string $property
31 * The property to retrieve.
34 * The value for that property, or NULL if the property does not exist.
36 public function get($property);
39 * Sets a value to an arbitrary property.
41 * @param string $property
42 * The property to use for the value.
48 public function set($property, $value);
51 * Gets the name of the original entity type class.
53 * In case the class name was changed with setClass(), this will return
54 * the initial value. Useful when trying to identify the entity type ID based
58 * The name of the original entity type class.
60 public function getOriginalClass();
63 * Gets an array of entity keys.
66 * An array describing how the Field API can extract certain information
67 * from objects of this entity type:
68 * - id: The name of the property that contains the primary ID of the
69 * entity. Every entity object passed to the Field API must have this
70 * property and its value must be numeric.
71 * - revision: (optional) The name of the property that contains the
72 * revision ID of the entity. The Field API assumes that all revision IDs
73 * are unique across all entities of a type. If this entry is omitted
74 * the entities of this type are not revisionable.
75 * - bundle: (optional) The name of the property that contains the bundle
76 * name for the entity. The bundle name defines which set of fields are
77 * attached to the entity (e.g. what nodes call "content type"). This
78 * entry can be omitted if this entity type exposes a single bundle (such
79 * that all entities have the same collection of fields). The name of this
80 * single bundle will be the same as the entity type.
81 * - label: (optional) The name of the property that contains the entity
82 * label. For example, if the entity's label is located in
83 * $entity->subject, then 'subject' should be specified here. If complex
84 * logic is required to build the label,
85 * \Drupal\Core\Entity\EntityInterface::label() should be used.
86 * - langcode: (optional) The name of the property that contains the
87 * language code. For instance, if the entity's language is located in
88 * $entity->langcode, then 'langcode' should be specified here.
89 * - uuid: (optional) The name of the property that contains the universally
90 * unique identifier of the entity, which is used to distinctly identify
91 * an entity across different systems.
93 public function getKeys();
96 * Gets a specific entity key.
99 * The name of the entity key to return.
101 * @return string|bool
102 * The entity key, or FALSE if it does not exist.
104 * @see self::getKeys()
106 public function getKey($key);
109 * Indicates if a given entity key exists.
112 * The name of the entity key to check.
115 * TRUE if a given entity key exists, FALSE otherwise.
117 public function hasKey($key);
120 * Indicates whether entities should be statically cached.
123 * TRUE if static caching should be used; FALSE otherwise.
125 public function isStaticallyCacheable();
128 * Indicates whether the rendered output of entities should be cached.
132 public function isRenderCacheable();
135 * Indicates if the persistent cache of field data should be used.
137 * @todo Used by ContentEntityStorageBase only.
139 * The persistent cache should usually only be disabled if a higher level
140 * persistent cache is available for the entity type.
144 public function isPersistentlyCacheable();
147 * Determines if there is a handler for a given type.
149 * @param string $handler_type
150 * The type of handler to check.
151 * @param bool $nested
152 * (optional) If this handler has a nested definition. Defaults to FALSE.
155 * TRUE if a handler of this type exists, FALSE otherwise.
157 public function hasHandlerClass($handler_type, $nested = FALSE);
160 * @param string $handler_type
161 * The handler type to get.
163 * @return array|string|null
164 * The handlers for a given type, or NULL if none exist.
166 public function getHandlerClass($handler_type);
169 * Gets an array of handlers.
172 * An associative array where the keys are the names of different handler
173 * types (listed below) and the values are the names of the classes that
174 * implement that handler:
175 * - storage: The name of the class used to load the objects. The class must
176 * implement \Drupal\Core\Entity\EntityStorageInterface.
177 * - form: An associative array where the keys are the names of the
178 * different form operations (such as 'create', 'edit', or 'delete') and
179 * the values are the names of the handler classes for those
180 * operations. The name of the operation is passed also to the form
181 * handler's constructor, so that one class can be used for multiple
182 * entity forms when the forms are similar. The classes must implement
183 * \Drupal\Core\Entity\EntityFormInterface.
184 * - list: The name of the class that provides listings of the entities. The
185 * class must implement \Drupal\Core\Entity\EntityListBuilderInterface.
186 * - render: The name of the class that is used to render the entities. The
187 * class must implement \Drupal\Core\Entity\EntityViewBuilderInterface.
188 * - access: The name of the class that is used for access checks. The class
189 * must implement \Drupal\Core\Entity\EntityAccessControlHandlerInterface.
190 * Defaults to \Drupal\Core\Entity\EntityAccessControlHandler.
191 * - route_provider: (optional) A list of class names, keyed by a group
192 * string, which will be used to define routes related to this entity
193 * type. These classes must implement
194 * \Drupal\Core\Entity\Routing\EntityRouteProviderInterface.
196 public function getHandlerClasses();
199 * Gets the storage class.
202 * The class for this entity type's storage.
204 public function getStorageClass();
207 * Sets the storage class.
209 * @param string $class
210 * The class for this entity type's storage.
214 public function setStorageClass($class);
217 * Gets the form class for a specific operation.
219 * @param string $operation
220 * The name of the operation to use, e.g., 'default'.
223 * The class for this operation's form for this entity type.
225 * @see \Drupal\Core\Entity\EntityFormBuilderInterface
227 public function getFormClass($operation);
230 * Sets a form class for a specific operation.
232 * @param string $operation
233 * The operation to use this form class for.
234 * @param string $class
235 * The form class implementing
236 * \Drupal\Core\Entity\EntityFormInterface.
240 * @see \Drupal\Core\Entity\EntityFormBuilderInterface
242 public function setFormClass($operation, $class);
245 * Indicates if this entity type has any forms.
248 * TRUE if there are any forms for this entity type, FALSE otherwise.
250 public function hasFormClasses();
253 * Indicates if this entity type has any route provider.
257 public function hasRouteProviders();
260 * Gets all the route provide handlers.
262 * Much like forms you can define multiple route provider handlers.
266 public function getRouteProviderClasses();
269 * Gets the list class.
272 * The class for this entity type's list.
274 public function getListBuilderClass();
277 * Sets the list class.
279 * @param string $class
280 * The list class to use for the operation.
284 public function setListBuilderClass($class);
287 * Indicates if this entity type has a list class.
290 * TRUE if there is a list for this entity type, FALSE otherwise.
292 public function hasListBuilderClass();
295 * Gets the view builder class.
298 * The class for this entity type's view builder.
300 public function getViewBuilderClass();
303 * Gets the view builder class.
305 * @param string $class
306 * The class for this entity type's view builder.
310 public function setViewBuilderClass($class);
313 * Indicates if this entity type has a view builder.
316 * TRUE if there is a view builder for this entity type, FALSE otherwise.
318 public function hasViewBuilderClass();
321 * Gets the access control class.
324 * The class for this entity type's access control.
326 public function getAccessControlClass();
329 * Gets the access class.
331 * @param string $class
332 * The class for this entity type's access.
336 public function setAccessClass($class);
339 * Indicates if the entity type class implements the given interface.
341 * @param string $interface
342 * The class or interface to check.
345 * TRUE if the entity type class implements the given interface.
347 public function entityClassImplements($interface);
350 * Indicates if the entity type is a subclass of the given class or interface.
352 * @param string $class
353 * The class or interface to check.
356 * TRUE if the entity type is a subclass of the class or interface.
358 * @deprecated in Drupal 8.3.0 and will be removed before Drupal 9.0.0.
359 * Use Drupal\Core\Entity\EntityTypeInterface::entityClassImplements()
362 public function isSubclassOf($class);
365 * Sets the handlers for a given type.
367 * @param string $handler_type
368 * The type of handler to set.
369 * @param array|string $value
370 * The value for a handler type.
374 public function setHandlerClass($handler_type, $value);
377 * Gets the name of the default administrative permission.
379 * The default \Drupal\Core\Entity\EntityAccessControlHandler class checks this
380 * permission for all operations in its checkAccess() method. Entities with
381 * more complex permissions can extend this class to do their own access
384 * @return string|bool
386 public function getAdminPermission();
389 * Gets the permission granularity level.
391 * The allowed values are respectively "entity_type" or "bundle".
394 * Whether a module exposing permissions for the current entity type
395 * should use entity-type level granularity or bundle level granularity.
397 public function getPermissionGranularity();
400 * Gets the link templates using the URI template syntax.
402 * Links are an array of standard link relations to the URI template that
403 * should be used for them. Where possible, link relationships should use
404 * established IANA relationships rather than custom relationships.
406 * Every entity type should, at minimum, define "canonical", which is the
407 * pattern for URIs to that entity. Even if the entity will have no HTML page
408 * exposed to users it should still have a canonical URI in order to be
409 * compatible with web services. Entities that will be user-editable via an
410 * HTML page must also define an "edit-form" relationship.
412 * By default, the following placeholders are supported:
413 * - [entityType]: The entity type itself will also be a valid token for the
414 * ID of the entity. For instance, a placeholder of {node} used on the Node
416 * - [bundleEntityType]: The bundle machine name itself. For instance, a
417 * placeholder of {node_type} used on the Node class.
419 * Specific entity types may also expand upon this list by overriding the
420 * Entity::urlRouteParameters() method.
422 * @link http://www.iana.org/assignments/link-relations/link-relations.xml @endlink
423 * @link http://tools.ietf.org/html/rfc6570 @endlink
427 public function getLinkTemplates();
430 * Gets the link template for a given key.
435 * @return string|bool
436 * The path for this link, or FALSE if it doesn't exist.
438 public function getLinkTemplate($key);
441 * Indicates if a link template exists for a given key.
447 * TRUE if the link template exists, FALSE otherwise.
449 public function hasLinkTemplate($key);
452 * Sets a single link template.
455 * The name of a link.
456 * @param string $path
457 * The route path to use for the link.
461 * @throws \InvalidArgumentException
462 * Thrown when the path does not start with a leading slash.
464 public function setLinkTemplate($key, $path);
467 * Gets the callback for the label of the entity.
469 * The function takes an entity and returns the label of the entity. Use
470 * language() on the entity to get information on the requested language. The
471 * entity label is the main string associated with an entity; for example, the
472 * title of a node or the subject of a comment. If there is an entity object
473 * property that defines the label, use the 'label' element of the
474 * 'entity_keys' return value component to provide this information. If more
475 * complex logic is needed to determine the label of an entity, you can
476 * instead specify a callback function here, which will be called to determine
479 * @return callable|null
480 * The callback, or NULL if none exists.
482 * @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 9.0.0.
483 * Use Drupal\Core\Entity\EntityInterface::label() for complex label
484 * generation as needed.
486 * @see \Drupal\Core\Entity\EntityInterface::label()
487 * @see \Drupal\Core\Entity\EntityTypeInterface::setLabelCallback()
488 * @see \Drupal\Core\Entity\EntityTypeInterface::hasLabelCallback()
490 * @todo Remove usages of label_callback https://www.drupal.org/node/2450793.
492 public function getLabelCallback();
495 * Sets the label callback.
497 * @param callable $callback
498 * A callable that returns the label of the entity.
502 * @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 9.0.0.
503 * Use EntityInterface::label() for complex label generation as needed.
505 * @see \Drupal\Core\Entity\EntityInterface::label()
506 * @see \Drupal\Core\Entity\EntityTypeInterface::getLabelCallback()
507 * @see \Drupal\Core\Entity\EntityTypeInterface::hasLabelCallback()
509 public function setLabelCallback($callback);
512 * Indicates if a label callback exists.
516 * @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 9.0.0.
517 * Use EntityInterface::label() for complex label generation as needed.
519 * @see \Drupal\Core\Entity\EntityInterface::label()
520 * @see \Drupal\Core\Entity\EntityTypeInterface::getLabelCallback()
521 * @see \Drupal\Core\Entity\EntityTypeInterface::setLabelCallback()
523 public function hasLabelCallback();
526 * Gets the name of the entity type which provides bundles.
528 * @return string|null
529 * The name of the entity type which provides bundles, or NULL if the entity
530 * type does not have a bundle entity type.
532 public function getBundleEntityType();
535 * Gets the entity type for which this entity provides bundles.
537 * It can be used by other modules to act accordingly; for example,
538 * the Field UI module uses it to add operation links to manage fields and
541 * @return string|null
542 * The entity type for which this entity provides bundles, or NULL if does
543 * not provide bundles for another entity type.
545 public function getBundleOf();
548 * Gets the label for the bundle.
550 * @return string|null
551 * The bundle label, or NULL if none exists.
553 public function getBundleLabel();
556 * Gets the name of the entity's base table.
558 * @todo Used by SqlContentEntityStorage only.
560 * @return string|null
561 * The name of the entity's base table, or NULL if none exists.
563 public function getBaseTable();
566 * Indicates whether entities of this type have multilingual support.
568 * At an entity level, this indicates language support and at a bundle level
569 * this indicates translation support.
573 public function isTranslatable();
576 * Indicates whether the revision form fields should be added to the form.
579 * TRUE if the form field should be added, FALSE otherwise.
581 public function showRevisionUi();
584 * Indicates whether entities of this type have revision support.
588 public function isRevisionable();
591 * Gets the name of the entity's revision data table.
593 * @todo Used by SqlContentEntityStorage only.
595 * @return string|null
596 * The name of the entity type's revision data table, or NULL if none
599 public function getRevisionDataTable();
602 * Gets the name of the entity's revision table.
604 * @todo Used by SqlContentEntityStorage only.
606 * @return string|null
607 * The name of the entity type's revision table, or NULL if none exists.
609 public function getRevisionTable();
612 * Gets the name of the entity's data table.
614 * @todo Used by SqlContentEntityStorage only.
616 * @return string|null
617 * The name of the entity type's data table, or NULL if none exists.
619 public function getDataTable();
622 * Gets the human-readable name of the entity type.
624 * This label should be used to present a human-readable name of the
628 * The human-readable name of the entity type.
630 public function getLabel();
633 * Gets the lowercase form of the human-readable entity type name.
636 * The lowercase form of the human-readable entity type name.
638 * @see \Drupal\Core\Entity\EntityTypeInterface::getLabel()
640 public function getLowercaseLabel();
643 * Gets the uppercase plural form of the name of the entity type.
645 * This should return a human-readable version of the name that can refer
646 * to all the entities of the given type, collectively. An example usage of
647 * this is the page title of a page devoted to a collection of entities such
648 * as "Workflows" (instead of "Workflow entities").
651 * The collection label.
653 public function getCollectionLabel();
656 * Gets the indefinite singular form of the name of the entity type.
658 * This should return the human-readable name for a single instance of
659 * the entity type. For example: "opportunity" (with the plural as
660 * "opportunities"), "child" (with the plural as "children"), or "content
661 * item" (with the plural as "content items").
664 * The singular label.
666 public function getSingularLabel();
669 * Gets the indefinite plural form of the name of the entity type.
671 * This should return the human-readable name for more than one instance of
672 * the entity type. For example: "opportunities" (with the singular as
673 * "opportunity"), "children" (with the singular as "child"), or "content
674 * items" (with the singular as "content item").
679 public function getPluralLabel();
682 * Gets the label's definite article form for use with a count of entities.
684 * This label should be used when the quantity of entities is provided. The
685 * name should be returned in a form usable with a count of the
686 * entities. For example: "1 opportunity", "5 opportunities", "1 child",
687 * "6 children", "1 content item", "25 content items".
690 * The item count to display if the plural form was requested.
695 public function getCountLabel($count);
698 * Gets a callable that can be used to provide the entity URI.
700 * This is only called if there is no matching link template for the link
701 * relationship type, and there is no bundle-specific callback provided.
703 * @return callable|null
704 * A valid callback that is passed the entity or NULL if none is specified.
706 public function getUriCallback();
709 * Sets a callable to use to provide the entity URI.
711 * @param callable $callback
712 * A callback to use to provide a URI for the entity.
716 public function setUriCallback($callback);
719 * Gets the machine name of the entity type group.
723 public function getGroup();
726 * Gets the human-readable name of the entity type group.
730 public function getGroupLabel();
733 * The list cache contexts associated with this entity type.
735 * Enables code listing entities of this type to ensure that rendered listings
736 * are varied as necessary, typically to ensure users of role A see other
737 * entities listed than users of role B.
741 public function getListCacheContexts();
744 * The list cache tags associated with this entity type.
746 * Enables code listing entities of this type to ensure that newly created
747 * entities show up immediately.
751 public function getListCacheTags();
754 * Gets the key that is used to store configuration dependencies.
757 * The key to be used in configuration dependencies when storing
758 * dependencies on entities of this type.
760 public function getConfigDependencyKey();
763 * Indicates whether this entity type is commonly used as a reference target.
766 * TRUE if the entity type is a common reference; FALSE otherwise.
768 public function isCommonReferenceTarget();
771 * Gets an array of validation constraints.
773 * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
774 * details on how constraints are defined.
777 * An array of validation constraint definitions, keyed by constraint name.
778 * Each constraint definition can be used for instantiating
779 * \Symfony\Component\Validator\Constraint objects.
781 * @see \Symfony\Component\Validator\Constraint
783 public function getConstraints();
786 * Sets the array of validation constraints for the FieldItemList.
788 * NOTE: This will overwrite any previously set constraints. In most cases
789 * ContentEntityTypeInterface::addConstraint() should be used instead.
790 * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
791 * details on how constraints are defined.
793 * @param array $constraints
794 * An array of validation constraint definitions, keyed by constraint name.
795 * Each constraint definition can be used for instantiating
796 * \Symfony\Component\Validator\Constraint objects.
800 * @see \Symfony\Component\Validator\Constraint
802 public function setConstraints(array $constraints);
805 * Adds a validation constraint.
807 * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
808 * details on how constraints are defined.
810 * @param string $constraint_name
811 * The name of the constraint to add, i.e. its plugin id.
812 * @param array|null $options
813 * The constraint options as required by the constraint plugin, or NULL.
817 public function addConstraint($constraint_name, $options = NULL);
820 * Gets the config dependency info for this entity, if any exists.
822 * @param string $bundle
826 * An associative array containing the following keys:
827 * - 'type': The config dependency type (e.g. 'module', 'config').
828 * - 'name': The name of the config dependency.
830 public function getBundleConfigDependency($bundle);