DRUPAL-HELPERS: Add entity helpers to retrieve values and translations

Author: Maarten Heip

src/EntityTraitWrapper.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Intracto\DrupalHelpers;
+
+use Intracto\DrupalHelpers\Traits\EntityHelperTrait;
+use Intracto\DrupalHelpers\Traits\ParagraphHelperTrait;
+
+/**
+ * Class EntityTraitWrapper.
+ *
+ * This class includes the helper traits so we can use it inside modules.
+ *
+ * @package Intracto\DrupalHelpers
+ */
+class EntityTraitWrapper {
+
+  use EntityHelperTrait;
+  use ParagraphHelperTrait;
+
+}

src/Traits/EntityHelperTrait.php

@@ -0,0 +1,191 @@
+<?php
+
+namespace Intracto\DrupalHelpers\Traits;
+
+use Drupal\Core\Entity\EntityInterface;
+use Drupal\Core\Entity\FieldableEntityInterface;
+use Drupal\Core\Field\FieldItemListInterface;
+use Drupal\Core\TypedData\TypedDataInterface;
+
+/**
+ * Trait EntityTranslationTrait.
+ *
+ * Provides helper functions to deal with entity value retrieval.
+ *
+ * @package Intraco\DrupalHelpers
+ */
+trait EntityHelperTrait {
+
+  use EntityTranslationTrait;
+
+  /**
+   * Gets the entity field value.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to retrieve the field value.
+   * @param string $field
+   *   The name of the field to return.
+   *
+   * @return null|string
+   *   The entity field value.
+   */
+  public function getEntityFieldValue(EntityInterface $entity, string $field) : ?string {
+    if (!$firstItem = $this->getFirstEntityFieldItem($entity, $field)) {
+      return NULL;
+    }
+
+    if (!$value = $firstItem->value) {
+      return NULL;
+    }
+
+    return $value;
+  }
+
+  /**
+   * Gets the entity field value.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to retrieve the field value.
+   * @param string $field
+   *   The name of the field to return.
+   *
+   * @return array
+   *   The entity field values.
+   */
+  public function getEntityFieldValues(EntityInterface $entity, string $field) : array {
+    if (!$list = $this->getEntityFieldList($entity, $field)) {
+      return [];
+    }
+
+    $values = [];
+
+    foreach ($list as $fieldItem) {
+      if (!$value = $fieldItem->value) {
+        continue;
+      }
+
+      $values[] = $value;
+    }
+
+    return $values;
+  }
+
+  /**
+   * Returns the referenced entities from a entity_reference field.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to retrieve the field value.
+   * @param string $field
+   *   The name of the field to return.
+   * @param bool $translated
+   *   Use the current entity langcode to return translated entities?
+   * @param bool $removeUntranslated
+   *   Skip a referenced entity that is not translated in the correct langcode.
+   *
+   * @return array
+   */
+  public function getReferencedEntitiesByField(EntityInterface $entity, string $field, bool $translated = TRUE, bool $removeUntranslated = FALSE) : array {
+    if (!$list = $this->getEntityFieldList($entity, $field)) {
+      return [];
+    }
+
+    $entities = [];
+
+    foreach ($list as $fieldItem) {
+      $entity = $fieldItem->entity;
+
+      if (!$entity) {
+        continue;
+      }
+
+      $entities[] = $entity;
+    }
+
+    if (!$translated) {
+      return $entities;
+    }
+
+    $activeLangcode = $entity->language()->getId();
+    return $this->translateEntities($entities, $activeLangcode, $removeUntranslated);
+  }
+
+  /**
+   * Returns the referenced entities from a entity_reference field.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to retrieve the field value.
+   * @param string $field
+   *   The name of the field to return.
+   * @param bool $translated
+   *   Use the current entity langcode to return translated entities?
+   * @param bool $removeUntranslated
+   *   Skip a referenced entity that is not translated in the correct langcode.
+   *
+   * @return \Drupal\Core\Entity\EntityInterface|null
+   *   The referenced entity.
+   */
+  public function getReferencedEntityByField(EntityInterface $entity, string $field, bool $translated = TRUE, bool $removeUntranslated = FALSE) : ?EntityInterface {
+    if (!$fieldItem = $this->getFirstEntityFieldItem($entity, $field)) {
+      return NULL;
+    }
+
+    if (!$referencedEntity = $fieldItem->entity) {
+      return NULL;
+    }
+
+    if (!$translated) {
+      return $referencedEntity;
+    }
+
+    $activeLangcode = $entity->language()->getId();
+    return $this->translateEntity($referencedEntity, $activeLangcode, $removeUntranslated);
+  }
+
+  /**
+   * Checks if an entity has a field and it has data.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to retrieve the field value.
+   * @param string $field
+   *   The name of the field to return.
+   *
+   * @return \Drupal\Core\Field\FieldItemListInterface|null
+   *   Whether or not entity has the field and has data for it.
+   */
+  public function getEntityFieldList(EntityInterface $entity, string $field) : ?FieldItemListInterface {
+    if (!$entity instanceof FieldableEntityInterface) {
+      return NULL;
+    }
+
+    if (!$entity->hasField($field)) {
+      return NULL;
+    }
+
+    $field = $entity->get($field);
+
+    if ($field->isEmpty()) {
+      return NULL;
+    }
+
+    return $field;
+  }
+
+  /**
+   * Returns the first item of a field list.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to retrieve the field item.
+   * @param string $field
+   *   The name of the field to return.
+   *
+   * @return \Drupal\Core\TypedData\TypedDataInterface|null
+   *   The field.
+   */
+  public function getFirstEntityFieldItem(EntityInterface $entity, string $field) : ?TypedDataInterface {
+    if (!$list = $this->getEntityFieldList($entity, $field)) {
+      return NULL;
+    }
+
+    return $list->first();
+  }
+}

src/Traits/EntityTranslationTrait.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace Intracto\DrupalHelpers\Traits;
+
+use Drupal\Core\Entity\EntityInterface;
+use Drupal\Core\Entity\TranslatableInterface;
+
+/**
+ * Trait EntityTranslationTrait.
+ *
+ * Provides helper functions to deal with entity translations.
+ *
+ * @package Intraco\DrupalHelpers
+ */
+trait EntityTranslationTrait {
+
+  /**
+   * Checks if an entity has a translations and returns the translated version.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   An entity that might contain a translation.
+   * @param string $langcode
+   *   The langcode in which to translate, leave empty to use current langcode.
+   * @param bool $required
+   *   If an entity is not translated, returns NULL if set to TRUE.
+   *
+   * @return \Drupal\Core\Entity\EntityInterface|null
+   *   The translated entity or null.
+   */
+  public function translateEntity(EntityInterface $entity, string $langcode = NULL, bool $required = FALSE) : ?EntityInterface {
+    if ($required) {
+      $returnEntity = NULL;
+    }
+    else {
+      $returnEntity = $entity;
+    }
+
+    if (!$langcode) {
+      $langcode = \Drupal::languageManager()
+        ->getCurrentLanguage()
+        ->getId();
+    }
+
+    if (!$entity instanceof TranslatableInterface) {
+      return $returnEntity;
+    }
+
+    if (!$entity->hasTranslation($langcode)) {
+      return $returnEntity;
+    }
+
+    return $entity->getTranslation($langcode);
+  }
+
+  /**
+   * Loops over an array of entities and returns translated entities.
+   *
+   * @param array $entities
+   *   An array of entities.
+   * @param string $langcode
+   *   The langcode in which to translate, leave empty to use current langcode.
+   * @param bool $removeUntranslated
+   *   Removes entities that are not translated.
+   *
+   * @return array
+   *   An array of translated entities
+   */
+  public function translateEntities(array $entities, string $langcode = NULL, bool $removeUntranslated = FALSE) : array {
+    // Get the langcode first so we don't have to fetch it in the loop.
+    if (!$langcode) {
+      $langcode = \Drupal::languageManager()
+        ->getCurrentLanguage()
+        ->getId();
+    }
+
+    foreach ($entities as $key => &$entity) {
+      if (!$entity instanceof EntityInterface) {
+        continue;
+      }
+
+      $entity = $this->translateEntity($entity, $langcode, $removeUntranslated);
+
+      // Unset an entity that is now a NULL.
+      // It will only be a NULL if translation is required.
+      // This is passed by the removeUntranslated variable.
+      if (!$entity) {
+        unset($entities[$key]);
+      }
+    }
+
+    return $entities;
+  }
+
+}

src/Traits/ParagraphHelperTrait.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Intracto\DrupalHelpers\Traits;
+
+use Drupal\Core\Entity\EntityInterface;
+use Drupal\node\NodeInterface;
+use Drupal\paragraphs\ParagraphInterface;
+
+/**
+ * Trait ParagraphHelperTrait
+ *
+ * @package Intracto\DrupalHelpers\Traits
+ */
+trait ParagraphHelperTrait {
+
+  /**
+   * Gets the node parent.
+   *
+   * @param \Drupal\paragraphs\ParagraphInterface $paragraph
+   *   The paragraph entity.
+   *
+   * @return \Drupal\Core\Entity\EntityInterface|null
+   *   The entity interface.
+   */
+  public function getNodeParent(ParagraphInterface $paragraph) : ?EntityInterface {
+    return self::getParentOfType($paragraph, NodeInterface::class);
+  }
+
+  /**
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to find a parent.
+   * @param string $type
+   *   The parent type to return.
+   *
+   * @return \Drupal\Core\Entity\EntityInterface|null
+   *   The entity interface.
+   */
+  public function getParentOfType(EntityInterface $entity, string $type) : ?EntityInterface {
+    if (!$entity instanceof ParagraphInterface) {
+      return NULL;
+    }
+
+    $parent = $entity->getParentEntity();
+
+    if ($parent instanceof $type) {
+      return $parent;
+    }
+
+    if ($parent instanceof EntityInterface) {
+      return self::getParentOfType($parent, $type);
+    }
+
+    return NULL;
+  }
+
+}