Entity API: Loading, Saving, Translating, Validating and Securing Entities

# meridian_collection.services.yml
services:
  meridian_collection.object_repository:
    class: Drupal\meridian_collection\CollectionObjectRepository
    autowire: true

  logger.channel.meridian_collection:
    parent: logger.channel_base
    arguments: ['meridian_collection']

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection;

use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Psr\Log\LoggerInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

/**
 * Reads and writes collection objects.
 */
class CollectionObjectRepository {

  public function __construct(
    protected EntityTypeManagerInterface $entityTypeManager,
    #[Autowire(service: 'logger.channel.meridian_collection')]
    protected LoggerInterface $logger,
  ) {}

  /**
   * The storage handler is cheap to ask for: the manager caches the instance.
   */
  protected function storage(): EntityStorageInterface {
    return $this->entityTypeManager->getStorage('collection_object');
  }

  /**
   * Loads one object by its numeric ID, or NULL when it does not exist.
   */
  public function load(int $id): ?ContentEntityInterface {
    $entity = $this->storage()->load($id);
    return $entity instanceof ContentEntityInterface ? $entity : NULL;
  }

  /**
   * Loads several objects at once, keyed by ID, in a single set of queries.
   *
   * @param int[] $ids
   *
   * @return \Drupal\Core\Entity\ContentEntityInterface[]
   */
  public function loadMany(array $ids): array {
    return $this->storage()->loadMultiple($ids);
  }

  /**
   * Finds the objects currently on display, ordered by accession number.
   *
   * accessCheck(TRUE) restricts the result to what the current user may view.
   *
   * @return \Drupal\Core\Entity\ContentEntityInterface[]
   */
  public function loadOnDisplay(int $limit = 50): array {
    $ids = $this->storage()->getQuery()
      ->accessCheck(TRUE)
      ->condition('on_display', 1)
      ->sort('accession_number')
      ->range(0, $limit)
      ->execute();
    return $this->storage()->loadMultiple($ids);
  }

  /**
   * Finds an object by accession number (no access check; internal use).
   */
  public function loadByAccessionNumber(string $accession): ?ContentEntityInterface {
    $found = $this->storage()->loadByProperties(['accession_number' => $accession]);
    $entity = reset($found);
    return $entity instanceof ContentEntityInterface ? $entity : NULL;
  }

}

$storage = $this->entityTypeManager->getStorage('collection_object');

// One entity by ID: the entity object, or NULL when there is no such ID.
$object = $storage->load(17);

// Several entities by ID, in one pass: an array keyed by entity ID.
// IDs that do not exist are simply missing from the result.
$objects = $storage->loadMultiple([17, 18, 19]);

// Every entity of the type, when called without an argument. Use with care.
$everything = $storage->loadMultiple();

// By exact field values. Matches ALL given properties.
$bronze = $storage->loadByProperties(['material' => 'Bronze', 'on_display' => 1]);

// $entityRepository is an injected EntityRepositoryInterface.
$object = $this->entityRepository->getTranslationFromContext($storage->load(17));

public function refreshAll(): void {
  $storage = $this->entityTypeManager->getStorage('collection_object');
  $ids = $storage->getQuery()->accessCheck(FALSE)->sort('id')->execute();
  foreach (array_chunk($ids, 100) as $chunk) {
    foreach ($storage->loadMultiple($chunk) as $object) {
      $this->refreshOne($object);
    }
    // Free the loaded objects: essential for Drush commands and workers.
    $storage->resetCache($chunk);
  }
}

// Roman objects on display whose label starts with "Coin", newest accession first.
$ids = $this->entityTypeManager->getStorage('collection_object')->getQuery()
  ->accessCheck(TRUE)
  ->condition('on_display', 1)
  ->condition('period', 'Roman')
  ->condition('name', 'Coin', 'STARTS_WITH')
  ->sort('accession_number', 'DESC')
  ->pager(20)
  ->execute();

# Evaluate PHP on the booted site (development only; never expose this).
ddev drush php:eval "print_r(\Drupal::entityTypeManager()->getStorage('collection_object')->load(17)->toArray());"

# Delete entities of a type (asks for confirmation; use --bundle for one bundle).
ddev drush entity:delete node --bundle=event

# Clear the caches after changing hooks or entity type definitions.
ddev drush cache:rebuild

public function create(string $accession, string $name, string $period): ContentEntityInterface {
  $object = $this->storage()->create([
    'name' => $name,
    'accession_number' => $accession,
    'period' => $period,
    'material' => 'Unknown',
    'on_display' => FALSE,
    'langcode' => 'en',
  ]);
  $this->logger->info('Created collection object %accession.', ['%accession' => $accession]);
  return $object;
}

public function importRow(array $row): int {
  $object = $this->loadByAccessionNumber($row['accession']) ?? $this->create($row['accession'], $row['name'], $row['period']);
  $object->set('material', $row['material']);
  $object->set('dimensions', $row['dimensions']);
  $object->set('on_display', (bool) $row['on_display']);

  // Run entity validation before writing: save() itself does not validate.
  $violations = $object->validate();
  if ($violations->count() > 0) {
    foreach ($violations as $violation) {
      $this->logger->warning('Row @row rejected: @field @message', [
        '@row' => $row['accession'],
        '@field' => $violation->getPropertyPath(),
        '@message' => (string) $violation->getMessage(),
      ]);
    }
    throw new \InvalidArgumentException('Invalid collection object.');
  }
  return $object->save();
}

// Single-valued scalar fields: the "main property" is value.
$name = $object->label();
$accession = $object->get('accession_number')->value;
$onDisplay = (bool) $object->get('on_display')->value;

// Safe checks before reading.
if ($object->hasField('dimensions') && !$object->get('dimensions')->isEmpty()) {
  $dimensions = $object->get('dimensions')->value;
}

// Multi-value field: iterate the items.
foreach ($exhibition->get('field_related_objects') as $delta => $item) {
  $targetId = $item->target_id;
}

// Entity reference fields: the loaded entities, with access and translation applied.
foreach ($exhibition->get('field_related_objects')->referencedEntities() as $related) {
  // Each $related is a collection_object entity.
}

// Raw arrays: one property array per item, or the whole entity as an array.
$rawValues = $object->get('period')->getValue();
$all = $object->toArray();

// A string rendering of the whole field (items joined), and the first item or NULL.
$text = $object->get('period')->getString();
$first = $object->get('period')->first();

// Replace a single value; the value is wrapped into the field's main property.
$object->set('period', 'Bronze Age');
$object->set('on_display', TRUE);

// Equivalent magic form (property access and assignment).
$object->period = 'Bronze Age';

// Replace all items of a multi-value or compound field.
$exhibition->set('field_related_objects', [
  ['target_id' => 17],
  ['target_id' => 18],
]);

// Add one item, remove one by delta, or empty the field.
$exhibition->get('field_related_objects')->appendItem(['target_id' => 19]);
$exhibition->get('field_related_objects')->removeItem(0);
$exhibition->set('field_related_objects', []);

// Set one property of an existing item.
$object->get('period')->first()->set('value', 'Iron Age');

$object->save();

// All field definitions of an entity (base fields plus configured fields of the bundle).
$definitions = $object->getFieldDefinitions();

// The definition behind one field, its storage, and the properties of its items.
$definition = $object->get('period')->getFieldDefinition();
$label = $definition->getLabel();
$type = $definition->getType();                // for example "string"
$isMultiple = $definition->getFieldStorageDefinition()->isMultiple();
$properties = $definition->getFieldStorageDefinition()->getPropertyDefinitions();

use Drupal\Core\TypedData\TypedDataManagerInterface;

public function isValidAccessionLength(string $value): bool {
  // $this->typedDataManager is an injected TypedDataManagerInterface.
  $definition = $this->typedDataManager->createDataDefinition('string');
  $definition->addConstraint('Length', ['max' => 24]);
  $data = $this->typedDataManager->create($definition, $value);
  return $data->validate()->count() === 0;
}

use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Field\BaseFieldDefinition;

public static function baseFieldDefinitions(EntityTypeInterface $entity_type): array {
  $fields = parent::baseFieldDefinitions($entity_type);

  $fields['accession_number'] = BaseFieldDefinition::create('string')
    ->setLabel(t('Accession number'))
    ->setRequired(TRUE)
    ->setSetting('max_length', 24)
    ->setRevisionable(TRUE)
    // Value must be unique among collection objects (case-insensitive by default).
    ->addConstraint('UniqueField')
    // Format check on the "value" property only.
    ->addPropertyConstraints('value', [
      'Regex' => ['pattern' => '/^MM\.\d{4}\.\d{3}$/'],
    ]);

  return $fields;
}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Plugin\Validation\Constraint;

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\Core\Validation\Attribute\Constraint;
use Symfony\Component\Validator\Attribute\HasNamedArguments;
use Symfony\Component\Validator\Constraint as SymfonyConstraint;

/**
 * An object on display needs a known period.
 */
#[Constraint(
  id: 'MeridianOnDisplayNeedsPeriod',
  label: new TranslatableMarkup('Object on display needs a period', [], ['context' => 'Validation']),
  type: ['entity'],
)]
class OnDisplayNeedsPeriodConstraint extends SymfonyConstraint {

  #[HasNamedArguments]
  public function __construct(
    public string $message = 'An object on display must have a period.',
    mixed ...$args,
  ) {
    parent::__construct(...$args);
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Plugin\Validation\Constraint;

use Drupal\Core\Entity\FieldableEntityInterface;
use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

/**
 * Validates OnDisplayNeedsPeriod. The class name is the constraint name plus "Validator".
 */
class OnDisplayNeedsPeriodConstraintValidator extends ConstraintValidator {

  public function validate(mixed $value, Constraint $constraint): void {
    assert($constraint instanceof OnDisplayNeedsPeriodConstraint);
    if (!$value instanceof FieldableEntityInterface) {
      return;
    }
    if ($value->get('on_display')->value && $value->get('period')->isEmpty()) {
      // atPath() ties the violation to the field, so the form highlights it.
      $this->context->buildViolation($constraint->message)
        ->atPath('period')
        ->addViolation();
    }
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Hook;

use Drupal\Core\Hook\Attribute\Hook;

/**
 * Attaches Meridian constraints to entity types owned by other modules.
 */
class CollectionConstraintHooks {

  /**
   * Implements hook_entity_type_alter().
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface[] $entity_types
   */
  #[Hook('entity_type_alter')]
  public function entityTypeAlter(array &$entity_types): void {
    if (isset($entity_types['node'])) {
      // Applies to every node. Constraints can be narrowed per bundle with
      // hook_entity_bundle_field_info_alter() on the bundle fields instead.
      $entity_types['node']->addConstraint('MeridianExhibitionDates');
    }
  }

}

$violations = $object->validate();

// All violations as messages, keyed by property path.
foreach ($violations as $violation) {
  printf("%s: %s\n", $violation->getPropertyPath(), $violation->getMessage());
}

// Only violations of one field, or only entity-level ones.
$periodViolations = $violations->getByField('period');
$entityLevel = $violations->getEntityViolations();

// Which fields failed.
$failedFields = $violations->getFieldNames();

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Hook;

use Drupal\Core\Cache\CacheTagsInvalidatorInterface;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Hook\Attribute\Hook;
use Drupal\node\NodeInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

/**
 * Cache and consistency reactions to entity changes.
 */
class CollectionEntityLifecycleHooks {

  public function __construct(
    #[Autowire(service: 'cache_tags.invalidator')]
    protected CacheTagsInvalidatorInterface $cacheTagsInvalidator,
  ) {}

  /**
   * A new translation was stored: the language specific listings change too.
   */
  #[Hook('collection_object_translation_insert')]
  public function translationAdded(EntityInterface $translation): void {
    $this->cacheTagsInvalidator->invalidateTags(['meridian_collection:objects']);
  }

  /**
   * Generic hook: runs for every entity type, so filter first.
   */
  #[Hook('entity_presave')]
  public function normaliseExhibition(EntityInterface $entity): void {
    if (!$entity instanceof NodeInterface || $entity->bundle() !== 'exhibition') {
      return;
    }
    $entity->setTitle(trim($entity->getTitle()));
  }

  /**
   * Compare the stored version with the saved one.
   */
  #[Hook('node_update')]
  public function exhibitionUpdated(NodeInterface $node): void {
    if ($node->bundle() !== 'exhibition') {
      return;
    }
    $original = $node->original ?? NULL;
    if ($original instanceof NodeInterface && $original->isPublished() !== $node->isPublished()) {
      $this->cacheTagsInvalidator->invalidateTags(['meridian_collection:exhibitions']);
    }
  }

}

// Boolean answer for the current user.
if ($object->access('update')) {
  // The user may edit this object.
}

// Rich answer with cacheability metadata, for use in render arrays and access callbacks.
$result = $object->access('view', $account, TRUE);

// Create access goes through the handler, because creating a temporary entity is costly.
$handler = $this->entityTypeManager->getAccessControlHandler('collection_object');
$mayCreate = $handler->createAccess('collection_object', $account);

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection;

use Drupal\Core\Access\AccessResult;
use Drupal\Core\Access\AccessResultInterface;
use Drupal\Core\Entity\EntityAccessControlHandler;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Session\AccountInterface;

/**
 * Access control for collection objects.
 */
class CollectionObjectAccessControlHandler extends EntityAccessControlHandler {

  /**
   * {@inheritdoc}
   */
  protected function checkAccess(EntityInterface $entity, $operation, AccountInterface $account): AccessResultInterface {
    // Curators and administrators can do anything (the parent grants the administer permission).
    $parent = parent::checkAccess($entity, $operation, $account);

    $result = match ($operation) {
      'view' => $entity->get('on_display')->value
        ? AccessResult::allowedIfHasPermission($account, 'view collection objects')
        : AccessResult::allowedIfHasPermission($account, 'view unpublished collection objects'),
      'update' => AccessResult::allowedIfHasPermission($account, 'edit collection objects'),
      'delete' => AccessResult::allowedIfHasPermission($account, 'delete collection objects'),
      default => AccessResult::neutral(),
    };

    // The decision depends on the permissions of the account and on the on_display value of the entity.
    return $parent->orIf($result)->addCacheableDependency($entity);
  }

  /**
   * {@inheritdoc}
   */
  protected function checkCreateAccess(AccountInterface $account, array $context, $entity_bundle = NULL): AccessResultInterface {
    return AccessResult::allowedIfHasPermissions($account, ['administer collection objects', 'create collection objects'], 'OR');
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Hook;

use Drupal\Core\Access\AccessResult;
use Drupal\Core\Access\AccessResultInterface;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Hook\Attribute\Hook;
use Drupal\Core\Session\AccountInterface;

/**
 * Entity access additions.
 */
class CollectionAccessHooks {

  /**
   * Implements hook_entity_access(): runs for every entity type.
   */
  #[Hook('entity_access')]
  public function entityAccess(EntityInterface $entity, string $operation, AccountInterface $account): AccessResultInterface {
    $forbid = $operation === 'delete'
      && $entity->getEntityTypeId() === 'node'
      && $entity->bundle() === 'exhibition'
      && !$account->hasPermission('administer collection objects');

    return AccessResult::forbiddenIf($forbid, 'Exhibitions can only be deleted by administrators.')
      ->cachePerPermissions()
      ->addCacheableDependency($entity);
  }

}