contextly-8.x-2.1/src/ContextlyBaseServiceInterface.php

<?php

namespace Drupal\contextly;

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

/**
 * The ContextlyBaseServiceInterface interface..
 */
interface ContextlyBaseServiceInterface {

  /**
   * Validate api key.
   *
   * @param string $key
   *   The api key.
   *
   * @return array
   *   The api key for validating.
   */
  public function settingsValidateApiKey(string $key): array;

  /**
   * Cp token value.
   *
   * @param string $type
   *   The token value type.
   *
   * @return string
   *   The token string.
   */
  public function settingsCpTokenValue(string $type): string;

  /**
   * Set api key token value.
   */
  public function settingsSetApiKeyTokenValue();

  /**
   * Cp tour redirecting.
   */
  public function settingsCpTourRedirect();

  /**
   * Set api key redirecting.
   */
  public function settingsSetApiKeyRedirect();

  /**
   * Reset the shared token.
   */
  public function settingsResetSharedToken();

  /**
   * Returns Contextly settings URL of specified type.
   *
   * @param string $type
   *   The route type.
   *
   * @return string
   *   The settings url.
   */
  public function settingsUrl($type);

  /**
   * Returns base URL of the Contextly server.
   *
   * URL depends on current mode: dev or production.
   *
   * @param string $server_type
   *   Possible types:
   *   - main: primary server with Contextly admin UI
   *   - api: server for API calls
   *   - cp: control panel (secure variant of the main server)
   * @param bool $secure
   *   The secure flag.
   *
   * @return string
   *   The server url.
   *
   * @todo Use the kit for this.
   */
  public function contextlyServerUrl($server_type,
    $secure = TRUE): string;

  /**
   * Return the contextly servers.
   *
   * @param string $scheme
   *   The request schema.
   *
   * @return array
   *   The servers array.
   */
  public function contextlyServers(string $scheme): array;

  /**
   * Logs passed exception using Drupal watchdog.
   *
   * @param \Exception $exception
   *   The exeption class.
   * @param string $message
   *   The message.
   */
  public function watchdogException(\Exception $exception,
    string $message = NULL);

  /**
   * Callback for both node update and insert.
   *
   * Send node of enabled type to the Contextly.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   */
  public function nodeChanged(NodeInterface $node);

  /**
   * Check contextly is enabled for node.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   */
  public function nodeContextlyIsDisabled(NodeInterface $node);

  /**
   * Saves Contextly settings of the node.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   */
  public function saveNodeRevisionSettings(NodeInterface $node);

  /**
   * Return the api key.
   *
   * @return array
   *   The api key.
   */
  public function getApiKey(): array;

  /**
   * Returns TRUE if API key was set.
   *
   * @return bool
   *   True if api key is a key set.
   */
  public function isApiKeySet(): bool;

  /**
   * Returns TRUE if passed node type is Contextly-enabled.
   *
   * @param string $type_name
   *   The node type.
   *
   * @return bool
   *   Return true if node type is enabled for contextly.
   */
  public function isNodeTypeEnabled(string $type_name): bool;

  /**
   * Delete the contextly settings of the given node revision.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   */
  public function removeNodeRevisionSettings(NodeInterface $node);

  /**
   * Returns the list of Contextly-enabled node types (machine names).
   *
   * @return array
   *   The enabled node types.
   */
  public function getEnabledTypes();

  /**
   * Returns JS settings required for the widgets.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   *
   * @return array
   *   The widget settings array.
   */
  public function nodeWidgetsSettings(NodeInterface $node): array;

  /**
   * Returns the list of field instances on Contextly-enabled node types.
   *
   * @param array $field_types
   *   The field types.
   *
   * @return array
   *   List of field names indexed by node type.
   */
  public function settingsGetAvailableFields(array $field_types);

  /**
   * Prepare render array.
   *
   * @param array $build
   *   The build array.
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The node entity.
   * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
   *   The display interface.
   * @param string $view_mode
   *   The view mode.
   */
  public function contextlyNodeView(array &$build,
    EntityInterface $entity,
    EntityViewDisplayInterface $display,
    string $view_mode);

  /**
   * Returns field names of selected types for the passed node type.
   *
   * @param string $node_type
   *   The node type.
   * @param array $field_types
   *   The field types.
   */
  public function getNodeTypeFields(string $node_type,
    array $field_types);

  /**
   * Formats timestamp before sending to the Contextly API.
   *
   * As a temporary solution, the date and time are formatted with website
   * default timezone for consistency independent from user timezone.
   *
   * @param int $timestamp
   *   The unix timestamp.
   *
   * @return string
   *   The formatted date.
   */
  public function formatDate(int $timestamp): string;

  /**
   * Return settings.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   *
   * @return array
   *   The settings array.
   */
  public function getSettings(NodeInterface $node): array;

}