<?php

namespace Drupal\uw_cfg_common\Service;

use Drupal\Core\Entity\EntityInterface;
use Drupal\node\NodeInterface;

/**
 * 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\NodeInterface $node
   *   Node entity.
   * @param array $variables_to_get
   *   List of variables to return.
   * @param string $teaser_type
   *   Teaser type.
   *
   * @return array
   *   Array of variables and their values.
   */
  public function getTeaserContent(NodeInterface $node, array $variables_to_get, string $teaser_type): 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;

  /**
   * 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);

}