EntityRepositoryInterface.php

<?php

namespace Drupal\Core\Entity;


/**
 * Provides an interface for an entity repository.
 */
interface EntityRepositoryInterface {
    
    /**
     * @deprecated in drupal:10.3.0 and is removed from drupal:12.0.0. There is no
     *   replacement.
     *
     * @see https://www.drupal.org/node/3437685
     */
    const CONTEXT_ID_LEGACY_CONTEXT_OPERATION = '@entity.repository:legacy_context_operation';
    
    /**
     * Loads an entity by UUID.
     *
     * Note that some entity types may not support UUIDs.
     *
     * @param string $entity_type_id
     *   The entity type ID to load from.
     * @param string $uuid
     *   The UUID of the entity to load.
     *
     * @return \Drupal\Core\Entity\EntityInterface|null
     *   The entity object, or NULL if there is no entity with the given UUID.
     *
     * @throws \Drupal\Core\Entity\EntityStorageException
     *   Thrown in case the requested entity type does not support UUIDs.
     */
    public function loadEntityByUuid($entity_type_id, $uuid);
    
    /**
     * Loads an entity by the config target identifier.
     *
     * @param string $entity_type_id
     *   The entity type ID to load from.
     * @param string $target
     *   The configuration target to load, as returned from
     *   \Drupal\Core\Entity\EntityInterface::getConfigTarget().
     *
     * @return \Drupal\Core\Entity\EntityInterface|null
     *   The entity object, or NULL if there is no entity with the given config
     *   target identifier.
     *
     * @throws \Drupal\Core\Entity\EntityStorageException
     *   Thrown if the target identifier is a UUID but the entity type does not
     *   support UUIDs.
     *
     * @see \Drupal\Core\Entity\EntityInterface::getConfigTarget()
     */
    public function loadEntityByConfigTarget($entity_type_id, $target);
    
    /**
     * Gets the entity translation to be used in the given context.
     *
     * This will check whether a translation for the desired language is available
     * and if not, it will fall back to the most appropriate translation based on
     * the provided context.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity whose translation will be returned.
     * @param string $langcode
     *   (optional) The language of the current context. Defaults to the current
     *   content language.
     * @param array $context
     *   (optional) An associative array of arbitrary data that can be useful to
     *   determine the proper fallback sequence. See
     *   \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates().
     *
     * @return \Drupal\Core\Entity\EntityInterface|null
     *   An entity object for the translated data, or NULL if the requested
     *   translation is missing, forbidden, or unavailable.
     *
     * @see \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates()
     */
    public function getTranslationFromContext(EntityInterface $entity, $langcode = NULL, $context = []);
    
    /**
     * Retrieves the active entity variant matching the specified context.
     *
     * If an entity type is revisionable and/or translatable, which entity variant
     * should be handled depends on the context in which the manipulation happens.
     * Based on the specified contextual information, revision and translation
     * negotiation needs to be performed to return the active variant, that is the
     * most up-to-date entity variant in the context scope. This may or may not be
     * an entity variant intended for unprivileged user consumption, in fact it
     * might be a work in progress containing yet to be published information. The
     * active variant should always be retrieved when editing an entity, both in
     * form and in REST workflows, or previewing the related changes.
     *
     * The negotiation process will not perform any access check, so it is the
     * responsibility of the caller to verify that the user manipulating the
     * entity variant is actually allowed to do so.
     *
     * @param string $entity_type_id
     *   The entity type identifier.
     * @param int|string $entity_id
     *   An entity identifier.
     * @param array|null $contexts
     *   (optional) An associative array of arbitrary data that can be useful to
     *   determine the proper fallback sequence. See
     *   \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates().
     *   Using context ids from the plugin context system is deprecated.
     *
     * @return \Drupal\Core\Entity\EntityInterface|null
     *   An entity object variant or NULL if the entity does not exist.
     */
    public function getActive($entity_type_id, $entity_id, ?array $contexts = NULL);
    
    /**
     * Retrieves the active entity variants matching the specified context.
     *
     * @param string $entity_type_id
     *   The entity type identifier.
     * @param int[]|string[] $entity_ids
     *   An array of entity identifiers.
     * @param array|null $contexts
     *   (optional) An associative array of arbitrary data that can be useful to
     *   determine the proper fallback sequence. See
     *   \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates().
     *   Using context ids from the plugin context system is deprecated.
     *
     * @return \Drupal\Core\Entity\EntityInterface[]
     *   An array of entity object variants keyed by entity ID.
     *
     * @see getActive()
     */
    public function getActiveMultiple($entity_type_id, array $entity_ids, ?array $contexts = NULL);
    
    /**
     * Retrieves the canonical entity variant matching the specified context.
     *
     * If an entity type is revisionable and/or translatable, which entity variant
     * should be handled depends on the context in which the manipulation happens.
     * This will return the fittest entity variant intended for unprivileged user
     * consumption matching the specified context. This is typically the variant
     * that would be displayed on the entity's canonical route.
     *
     * The negotiation process will not perform any access check, so it is the
     * responsibility of the caller to verify that the user manipulating the
     * entity variant is actually allowed to do so.
     *
     * @param string $entity_type_id
     *   The entity type identifier.
     * @param int|string $entity_id
     *   An entity identifier.
     * @param array|null $contexts
     *   (optional) An associative array of arbitrary data that can be useful to
     *   determine the proper fallback sequence. See
     *   \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates().
     *   Using context ids from the plugin context system is deprecated.
     *
     * @return \Drupal\Core\Entity\EntityInterface|null
     *   An entity object variant or NULL if the entity does not exist.
     */
    public function getCanonical($entity_type_id, $entity_id, ?array $contexts = NULL);
    
    /**
     * Retrieves the canonical entity variants matching the specified context.
     *
     * @param string $entity_type_id
     *   The entity type identifier.
     * @param int[]|string[] $entity_ids
     *   An array of entity identifiers.
     * @param array|null $contexts
     *   (optional) An associative array of arbitrary data that can be useful to
     *   determine the proper fallback sequence. See
     *   \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates().
     *   Using context ids from the plugin context system is deprecated.
     *
     * @return \Drupal\Core\Entity\EntityInterface[]
     *   An array of entity object variants keyed by entity ID.
     *
     * @see getCanonical()
     */
    public function getCanonicalMultiple($entity_type_id, array $entity_ids, ?array $contexts = NULL);

}