Trabajo con la API de Entidades (Entity API)

Cubre los métodos API del objeto general

• Entity::create()
• Entity::load()
• Entity::save()
• Entity::id()
• Entity::bundle()
• Entity::isNew()
• Entity::label()

Las API más específicas se cubrirán en capítulos dedicados.

Verificación

// Asegúrate de que un objeto sea una entidad.
if ($entity instanceof \Drupal\Core\Entity\EntityInterface) {
}

// Asegúrate de que sea una entidad de contenido.
if ($entity instanceof \Drupal\Core\Entity\ContentEntityInterface) {
}
// o:
if ($entity->getEntityType()->getGroup() == 'content') {
}

// Obtener el tipo de entidad o el ID del tipo de entidad.
$entity->getEntityType();
$entity->getEntityTypeId();

// Asegúrate de que sea un nodo.
if ($entity instanceof \Drupal\node\NodeInterface) {
}

Obtener información desde entity / Métodos de Entity

Hay varios métodos generales disponibles para obtener información de un objeto, como el identificador, el paquete, el ID de revisión, etc. Consulta la documentación en EntityInterface para más detalles.

// Obtener el ID.
$entity->id();

// Obtener el bundle.
$entity->bundle();

// Comprobar si la entidad es nueva.
$entity->isNew();

// Obtener la etiqueta de una entidad. Reemplazo de entity_label().
$entity->label();

// Obtener el objeto URL de una entidad.
$entity->toUrl();

// Obtener la ruta interna, alias si existe, para una entidad.
$entity->toUrl()->toString();

// Crear un duplicado que pueda ser guardado como una nueva entidad.
$duplicate = $entity->createDuplicate();

Creación de una entidad

// Puedes usar el método estático create() si conoces la clase de la entidad.
$node = Node::create([
  'type' => 'article',
  'title' => 'El título del nodo',
]);

// Usar el administrador de tipos de entidad (recomendado).
$node = \Drupal::entityTypeManager()->getStorage('node')->create(['type' => 'article', 'title' => 'Otro nodo']);

// O usar el envoltorio procedimental (obsoleto).
$node = entity_create('node', [
  'title' => 'Mi nodo',
  'body' => 'El contenido del cuerpo. Esto funciona así gracias a la nueva Entity Field API.
          Se asignará como valor del primer elemento del campo
          en el idioma predeterminado.',
]);

Las configuraciones por defecto definidas en la anotación del tipo de campo solo se añaden para claves de nivel superior que falten; no se realiza una fusión profunda.

Evita usar el método estático Entity::create() en código orientado a objetos. En su lugar, usa inyección de dependencias para inyectar el administrador de tipos de entidad y crear la entidad con $this->entityTypeManager->getStorage($entity_type)->create(). Esto asegura que el código esté bien separado y pueda ser testeado por el módulo.

Para mejor soporte en IDE, también puedes asignar la interfaz de almacenamiento de entidades a una propiedad. Por ejemplo, $this->nodeStorage = $this->entityTypeManager->getStorage('node'); Para crear una entidad, puedes usar $this->nodeStorage->create().

Carga

// Usar el método estático
$node = Node::load(1);

// Obsoleto. Tipo dinámico de entidad, entity_load() ahora carga una única entidad, entity_load_multiple() reemplaza a la función 7.x.
$entity = entity_load($entity_type, $id);

// Usando el controlador de almacenamiento (recomendado).
$entity = \Drupal::entityTypeManager()->getStorage($entity_type)->load(1);

// Cargar múltiples entidades, también existe entity_load_multiple().
$entities = \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple([1, 2, 3]);

// Cargar entidades por sus valores de propiedad.
$entities = \Drupal::entityTypeManager()->getStorage('node')->loadByProperties(['type' => 'article']);

Para actualizar un objeto, cárgalo y luego guarda con los cambios.

Evita usar el método estático Entity::load() en código orientado a objetos. En su lugar, usa inyección de dependencias para inyectar el administrador de tipos de entidad y cargar la entidad con $this->entityTypeManager->getStorage($entity_type)->load($entity_id). Esto asegura que el código esté bien separado y pueda ser testeado por el módulo.

Guardar una entidad

// Para guardar una entidad.
$entity->save();

Esto funciona tanto para entidades nuevas como existentes, la entidad misma rastrea si es nueva o no. Por defecto, para entidades de contenido esto depende de si tiene un identificador o no. Para guardar un objeto con un ID como uno nuevo (por ejemplo, en importaciones), puedes usar la bandera isNew.

// Lo siguiente intentará insertar un nodo nuevo con ID 5, esto fallará si el nodo ya existe.
$node->nid->value = 5;
$node->enforceIsNew(TRUE);
$node->save();

Eliminar una entidad

// Eliminar una sola entidad.
$entity = \Drupal::entityTypeManager()->getStorage('node')->load(1);
$entity->delete();

// Eliminar múltiples entidades a la vez.
\Drupal::entityTypeManager()->getStorage($entity_type)->delete([$id1 => $entity1, $id2 => $entity2]);

Control de acceso

El método access() se puede usar para verificar quién puede hacer qué con la entidad. El método soporta varias operaciones, las operaciones estándar son view (ver), update (actualizar), delete (eliminar) y create (crear), esta última es algo especial, véase más abajo.

Las verificaciones de acceso se delegan al controlador de acceso. (TODO: Añadir enlace)

// Comprobar acceso para ver una entidad.
// Por defecto comprueba el acceso para el usuario actual.
if ($entity->access('view')) {

}

// Comprobar si un usuario dado puede eliminar una entidad.
if ($entity->access('delete', $account)) {

}

Al comprobar el acceso para crear, normalmente la entidad no existe aún. Crear una entidad solo para comprobar si alguien puede crearla es una operación costosa. Por eso el acceso para creación debe ser verificado directamente en el controlador de acceso.

\Drupal::entityTypeManager()->getAccessControlHandler('node')->createAccess('article');

Si la entidad ya existe, $entity->access('create') también funciona, que simplemente redirige al método createAccess(), igual que otras operaciones que redirigen el método access() al controlador de acceso.

NOTA. En algunas guías online se usa \Drupal::entityManager(), pero en la versión 8.x está obsoleto y será eliminado en la versión 9.x. Por ello, puedes usar \Drupal::entityTypeManager() en lugar de \Drupal::entityManager().