UWServiceInterface.php

<?php

namespace Drupal\uw_cfg_common\Service;

use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Field\EntityReferenceFieldItemListInterface;
use Drupal\node\Entity\Node;

/**
 * Interface UWServiceInterface.
 *
 * Interface that is collection of common functions used in custom blocks.
 *
 * @package Drupal\uw_cfg_common\Service
 */
interface UWServiceInterface {

  /**
   * Prepares responsive image.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   Image entity.
   * @param string $image_style
   *   Image style to be used for responsive image.
   *
   * @return array
   *   Array with details for responsive image.
   */
  public function prepareResponsiveImage(EntityInterface $entity, string $image_style): array;

  /**
   * Prepares teaser.
   *
   * @param \Drupal\node\Node $node
   *   Node entity.
   * @param string $view_mode
   *   The view mode (i.e. node, teaser, etc).
   * @param string $content
   *   The type of content to get, values are all, header or footer.
   *
   * @return array
   *   Array of variables and their values.
   */
  public function uwGetNodeContent(Node $node, string $view_mode, string $content = 'all'): array;

  /**
   * Gets teaser data.
   *
   * @param \Drupal\node\Node $node
   *   Node entity.
   * @param string $view_mode
   *   The view mode (i.e. node, teaser, etc).
   * @param array $content_data
   *   An array of all the data to get for the teaser.
   *
   * @return array
   *   Array of node values.
   */
  public function uwGetNodeData(Node $node, string $view_mode, array $content_data): array;

  /**
   * Gets content types that have feature images.
   *
   * @return array
   *   Array of content types that has featured images.
   */
  public function uwGetFeaturedImageContentTypes(): array;

  /**
   * Gets dates from node.
   *
   * @param \Drupal\node\Node $node
   *   Node entity.
   * @param string $field_name
   *   The field name that has the date(s).
   *
   * @return array
   *   Array of dates.
   */
  public function uwGetDates(Node $node, string $field_name): array;

  /**
   * Gets image from node.
   *
   * @param \Drupal\node\Node $node
   *   Node entity.
   * @param string $field_name
   *   The field name that has the date(s).
   *
   * @return array
   *   array with image information.
   */
  public function uwGetImage(Node $node, string $field_name): array;

  /**
   * Gets sources from node.
   *
   * @param \Drupal\node\Node $node
   *   Node entity.
   * @param string $field_name
   *   The field name that has the date(s).
   *
   * @return array
   *   Either array with responsive image.
   */
  public function uwGetSources(Node $node, string $field_name): array;

  /**
   * Gets link info from node.
   *
   * @param \Drupal\node\Node $node
   *   Node entity.
   * @param string $field_name
   *   The field name that has the date(s).
   *
   * @return array
   *   Array with link info.
   */
  public function uwGetLinkInfo(Node $node, string $field_name): array;

  /**
   * A function to get or check the attached sidebar.
   *
   * If the type is set to check, then the function will return one
   * of two things. It will either return a 0, which means that the
   * attached_page_nid is not attached to any other sidebar in the
   * system.  Or it will return the entity_id of the sidebar (sidebar_nid)
   * that it is currently attached to.
   *
   * For example:
   *   If the attached_page_nid is 3 and the sidebar_nid is 7, and
   *   the query finds that 3 is already attached to sidebar_nid 6, then 6
   *   will be returned.
   *
   *   If the attached_page_nid is 3 and the sidebar_nid is 7, and
   *   the query finds no other sidebar_nids that 3 is attached to, then 0
   *   will be returned.
   *
   * @param int $attached_page_nid
   *   An integer value that represents the nid of the page to be attached to.
   * @param int|null $sidebar_nid
   *   An integer value that represents the nid of the current sidebar.
   * @param string|null $type
   *   A string value that represents either "get" or "check".
   *
   * @return int
   *   A value that is either 0 (no nids) or the entity_id of a sidebar.
   */
  public function getOrCheckAttachedSidebar(int $attached_page_nid, int $sidebar_nid = NULL, string $type = NULL): int;

  /**
   * A function to get an array of UW content types, with or without sidebar.
   *
   * @param bool $with_sidebar
   *   A boolean to state if we want content types that can have sidebars.
   *
   * @return array
   *   An array of the machine names of the UW content types.
   */
  public function getUwContentTypes(bool $with_sidebar = FALSE): array;

  /**
   * A function to get an array of menu.
   *
   * @param string $menu_name
   *   A string to the machine name of the menu to get.
   * @param bool $count_menu_items
   *   A boolean on whether to count the number of menu items.
   * @param bool $include_parent_in_count
   *   A boolean on whether to include the parent in the menu items count.
   *
   * @return array
   *   An array of the menu.
   */
  public function uwGetMenu(string $menu_name = 'main', bool $count_menu_items = FALSE, bool $include_parent_in_count = FALSE): array;

  /**
   * Function to check that all menu links are published.
   *
   * @param array $menu
   *   The array of menus.
   */
  public function uwCheckPublishedMenuItems(array &$menu): void;

  /**
   * A function to setup the menu for UW display.
   *
   * This function will count of the number of menu items,
   * and use a recursive function (uwCountMenuItems) to count
   * the total number of menu items.
   *
   * The variable include_parent_in_count tells us if we need
   * to add one to the total count of menu items.  This is required
   * for displaying some menus as the parent is also included
   * in the displaying of the menu (i.e. the tray of the main and
   * information for menus).
   *
   * For example, the menu structure will look like:
   * Parent
   *   Child #1
   *     Grandchild #1-1
   *     Grandchild #1-2
   *   Child #2
   *   Child #3
   *     Grandchild #3-1
   *       Great grandchild #3-1-1
   *       Great grandchild #3-1-2
   *     Grandchild #3-2
   *     Grandchild #3-3
   *       Great grandchild #3-3-1
   * So it should with the recursive function it will return 11.
   * If we include the parent the count will be 12.
   *
   * @param array $menus
   *   A reference to the array list of menu items.
   * @param bool $include_parent_in_count
   *   A boolean on whether to include the parent in the menu items count.
   *
   * @return array
   *   An array of the updated menu items.
   */
  public function uwSetMenuItems(array $menus, bool $include_parent_in_count = FALSE): array;

  /**
   * A function to recursively count the number of menu items in the submenu.
   *
   * @param array $menu
   *   An array that contains the submenu.
   * @param int &$menu_items_count
   *   A reference to the integer that is storing the number of menu items.
   */
  public function uwCountMenuItems(array $menu, int &$menu_items_count): void;

  /**
   * A function to return the month short name.
   *
   * @param int $month
   *   An integer of the month.
   *
   * @return mixed
   *   A mixed variable that will either be a string of the short
   *   month with a period or array of all short months.
   */
  public function uwMonthNameShort(int $month = NULL);

  /**
   * A function get the taxonomy terms.
   *
   * @param array $tids
   *   An array of term ids (tids).
   * @param string $type
   *   The type of terms to get, if none provided just term name returned.
   *
   * @return array
   *   An array of terms with name and link.
   */
  public function uwGetTerms(array $tids, string $type = NULL): array;

  /**
   * A function to get the footer data for a node/content type.
   *
   * @param \Drupal\node\Entity\Node $node
   *   The node object.
   *
   * @return array
   *   An array of author name and link.
   */
  public function uwGetAuthor(Node $node): array;

  /**
   * Function that parses terms and returns a list.
   *
   * @param \Drupal\Core\Field\EntityReferenceFieldItemListInterface $values
   *   List of values for the provided field.
   * @param string|null $type
   *   The type of terms to get, if none provided just term name returned.
   *
   * @return array
   *   List of terms with name and link.
   *
   * @throws \Drupal\Core\Entity\EntityMalformedException
   */
  public function uwGetTermsFromEntityField(EntityReferenceFieldItemListInterface $values, string $type = NULL): array;

}