Drupal  8.3.5
APl Documentation
Entity API

Data Structures

interface  AccessibleInterface
 
class  ConfigEntityBase
 
interface  ConfigEntityInterface
 
class  ConfigEntityListBuilder
 
class  ConfigEntityStorage
 
class  ConfigEntityType
 
class  ContentEntityType
 
class  EntityType
 
class  ContentEntityBase
 
interface  ContentEntityInterface
 
class  EntityConfirmFormBase
 
class  EntityDeleteForm
 
class  EntityForm
 
class  EntityHandlerBase
 
interface  EntityHandlerInterface
 
interface  EntityInterface
 
class  EntityListBuilder
 
interface  EntityStorageInterface
 
class  EntityType
 
class  EntityViewBuilder
 
interface  EntityViewBuilderInterface
 
interface  FieldableEntityInterface
 
class  RevisionableContentEntityBase
 
class  SqlContentEntityStorage
 
class  ContentTranslationHandler
 

Functions

 hook_entity_access (\Drupal\Core\Entity\EntityInterface $entity, $operation, \Drupal\Core\Session\AccountInterface $account)
 
 hook_ENTITY_TYPE_access (\Drupal\Core\Entity\EntityInterface $entity, $operation, \Drupal\Core\Session\AccountInterface $account)
 
 hook_entity_create_access (\Drupal\Core\Session\AccountInterface $account, array $context, $entity_bundle)
 
 hook_ENTITY_TYPE_create_access (\Drupal\Core\Session\AccountInterface $account, array $context, $entity_bundle)
 

Variables

trait EntityDeleteFormTrait
 

Detailed Description

Describes how to define and manipulate content and configuration entities.

Entities, in Drupal, are objects that are used for persistent storage of content and configuration information. See the Information types topic for an overview of the different types of information, and the Configuration API topic for more about the configuration API.

Each entity is an instance of a particular "entity type". Some content entity types have sub-types, which are known as "bundles", while for other entity types, there is only a single bundle. For example, the Node content entity type, which is used for the main content pages in Drupal, has bundles that are known as "content types", while the User content type, which is used for user accounts, has only one bundle.

The sections below have more information about entities and the Entity API; for more detailed information, see https://www.drupal.org/developing/api/entity.

Defining an entity type

Entity types are defined by modules, using Drupal's Plugin API (see the Plugin API topic for more information about plugins in general). Here are the steps to follow to define a new entity type:

Entity routes

Entity routes can be defined in *.routing.yml files, like any other route: see the Routing API topic for more information. Another option for entity routes is to use a route provider class, and reference it in the annotations on the entity class: see the end of this section for an example.

It's possible to use both a YAML file and a provider class for entity routes, at the same time. Avoid duplicating route names between the two: if a duplicate route name is found in both locations, the one in the YAML file takes precedence; regardless, such duplication can be confusing.

Here's an example YAML route specification, for the block configure form:

entity.block.edit_form:
path: '/admin/structure/block/manage/{block}'
defaults:
_entity_form: 'block.default'
_title: 'Configure block'
requirements:
_entity_access: 'block.update'

Some notes on this example:

To register any route provider class, add lines like the following to your entity class annotation:

handlers = {
"route_provider" = {
"html" = "Drupal\Core\Entity\Routing\DefaultHtmlRouteProvider",

Defining a content entity bundle

For entity types that use bundles, such as Node (bundles are content types) and Taxonomy (bundles are vocabularies), modules and install profiles can define bundles by supplying default configuration in their config/install directories. (See the Configuration API topic for general information about configuration.)

There are several good examples of this in Drupal Core:

Loading, querying, and rendering entities

To load entities, use the entity storage manager, which is an object implementing that you can retrieve with:

$storage = \Drupal::entityManager()->getStorage('your_entity_type');
// Or if you have a $container variable:
$storage = $container->get('entity.manager')->getStorage('your_entity_type');

Here, 'your_entity_type' is the machine name of your entity type ('id' annotation on the entity class), and note that you should use dependency injection to retrieve this object if possible. See the Services and Dependency Injection topic for more about how to properly retrieve services.

To query to find entities to load, use an entity query, which is a object implementing that you can retrieve with:

// Simple query:
$query = \Drupal::entityQuery('your_entity_type');
// Or, if you have a $container variable:
$storage = $container->get('entity_type.manager')->getStorage('your_entity_type');
$query = $storage->getQuery();

If you need aggregation, there is an aggregate query available, which implements :

$query \Drupal::entityQueryAggregate('your_entity_type');
// Or:
$query = $storage->getAggregateQuery('your_entity_type');

In either case, you can then add conditions to your query, using methods like condition(), exists(), etc. on $query; add sorting, pager, and range if needed, and execute the query to return a list of entity IDs that match the query.

Here is an example, using the core File entity:

$fids = Drupal::entityQuery('file')
->condition('status', FILE_STATUS_PERMANENT, '<>')
->condition('changed', REQUEST_TIME - $age, '<')
->range(0, 100)
->execute();
$files = $storage->loadMultiple($fids);

The normal way of viewing entities is by using a route, as described in the sections above. If for some reason you need to render an entity in code in a particular view mode, you can use an entity view builder, which is an object implementing that you can retrieve with:

$view_builder = \Drupal::entityManager()->getViewBuilder('your_entity_type');
// Or if you have a $container variable:
$view_builder = $container->get('entity.manager')->getViewBuilder('your_entity_type');

Then, to build and render the entity:

// You can omit the language ID, by default the current content language will
// be used. If no translation is available for the current language, fallback
// rules will be used.
$build = $view_builder->view($entity, 'view_mode_name', $language->getId());
// $build is a render array.
$rendered = drupal_render($build);

Access permission checking

Entity types define their access permission scheme in their annotation. Access permissions can be quite complex, so you should not assume any particular permission scheme. Instead, once you have an entity object loaded, you can check for permission for a particular operation (such as 'view') at the entity or field level by calling:

$entity->access($operation);
$entity->nameOfField->access($operation);

The interface related to access checking in entities and fields is .

The default entity access control handler invokes two hooks while checking access on a single entity: hook_entity_access() is invoked first, and then hook_ENTITY_TYPE_access() (where ENTITY_TYPE is the machine name of the entity type). If no module returns a TRUE or FALSE value from either of these hooks, then the entity's default access checking takes place. For create operations (creating a new entity), the hooks that are invoked are hook_entity_create_access() and hook_ENTITY_TYPE_create_access() instead.

The Node entity type has a complex system for determining access, which developers can interact with. This is described in the Node access topic.

See also
Internationalization
Entity CRUD, editing, and view hooks
::getTranslationFromContext()

Function Documentation

◆ hook_entity_access()

hook_entity_access ( \Drupal\Core\Entity\EntityInterface  $entity,
  $operation,
\Drupal\Core\Session\AccountInterface  $account 
)

Control entity operation access.

Parameters
\Drupal\Core\Entity\EntityInterface$entityThe entity to check access to.
string$operationThe operation that is to be performed on $entity.
\Drupal\Core\Session\AccountInterface$accountThe account trying to access the entity.
Returns
The access result. The final result is calculated by using ::orIf() on the result of every hook_entity_access() and hook_ENTITY_TYPE_access() implementation, and the result of the entity-specific checkAccess() method in the entity access control handler. Be careful when writing generalized access checks shared between routing and entity checks: routing uses the andIf() operator. So returning an isNeutral() does not determine entity access at all but it always ends up denying access while routing.
See also
hook_entity_create_access()
hook_ENTITY_TYPE_access()

Definition at line 564 of file entity.api.php.

◆ hook_entity_create_access()

hook_entity_create_access ( \Drupal\Core\Session\AccountInterface  $account,
array  $context,
  $entity_bundle 
)

Control entity create access.

Parameters
\Drupal\Core\Session\AccountInterface$accountThe account trying to access the entity.
array$contextAn associative array of additional context values. By default it contains language and the entity type ID:
  • entity_type_id - the entity type ID.
  • langcode - the current language code.
string$entity_bundleThe entity bundle name.
Returns
The access result.
See also
hook_entity_access()
hook_ENTITY_TYPE_create_access()

Definition at line 615 of file entity.api.php.

◆ hook_ENTITY_TYPE_access()

hook_ENTITY_TYPE_access ( \Drupal\Core\Entity\EntityInterface  $entity,
  $operation,
\Drupal\Core\Session\AccountInterface  $account 
)

Control entity operation access for a specific entity type.

Parameters
\Drupal\Core\Entity\EntityInterface$entityThe entity to check access to.
string$operationThe operation that is to be performed on $entity.
\Drupal\Core\Session\AccountInterface$accountThe account trying to access the entity.
Returns
The access result. hook_entity_access() has detailed documentation.
See also
hook_ENTITY_TYPE_create_access()
hook_entity_access()

Definition at line 588 of file entity.api.php.

◆ hook_ENTITY_TYPE_create_access()

hook_ENTITY_TYPE_create_access ( \Drupal\Core\Session\AccountInterface  $account,
array  $context,
  $entity_bundle 
)

Control entity create access for a specific entity type.

Parameters
\Drupal\Core\Session\AccountInterface$accountThe account trying to access the entity.
array$contextAn associative array of additional context values. By default it contains language:
  • langcode - the current language code.
string$entity_bundleThe entity bundle name.
Returns
The access result.
See also
hook_ENTITY_TYPE_access()
hook_entity_create_access()

Definition at line 641 of file entity.api.php.

Variable Documentation

◆ EntityDeleteFormTrait

trait EntityDeleteFormTrait
Initial value:

Provides a trait for an entity deletion form.

This trait relies on the StringTranslationTrait and the logger method added by FormBase.

Definition at line 17 of file EntityDeleteFormTrait.php.