<?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;

}