<?php

namespace Drupal\acquia_dam\Plugin\media\acquia_dam;

use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\media\MediaInterface;

/**
 * Describes a DAM Asset compliant Media Source type for media items.
 */
interface MediaSourceTypeInterface extends ContainerFactoryPluginInterface {

  /**
   * Sets the configuration for this plugin instance.
   *
   * @param array $configuration
   *   An associative array containing the plugin's configuration.
   */
  public function setConfiguration(array $configuration): void;

  /**
   * Gets this plugin's configuration.
   *
   * @return array
   *   An array of this plugin's configuration.
   */
  public function getConfiguration(): array;

  /**
   * Get the actual local file asset field defined by the active plugin.
   *
   * @return string
   *   The Local File Asset Field.
   */
  public function getLocalFileAssetField(): string;

  /**
   * Returns the default file extensions for the local managed file field.
   *
   * Each derivative plugin (Video, Audio, etc.) declares its accepted file
   * extensions inside its $assetFieldFormatterConfiguration array. This method
   * exposes that value so that Asset::defaultConfiguration() can seed the
   * source configuration with the correct extensions when a new media type is
   * created, ensuring ManagedFileField::getFieldDefinition() applies the right
   * file extension constraint.
   *
   * @return string
   *   Space-separated file extensions, or an empty string
   *   if the derivative plugin does not define any.
   */
  public function getDefaultFileExtensions(): string;

  /**
   * Get the name of the actual field used to represent an asset.
   *
   * Assets are represented by one field, but that field can change depending on the asset being shown.
   *
   * @return string
   *   The Asset Field Name.
   */
  public function getActiveFieldName(): string;

  /**
   * Get the formatter settings for a particular asset field.
   *
   * This method is used by acquia_dam_entity_bundle_field_info to set some formatter settings on the field storage.
   *
   * @param $managed_field_name
   *   The Managed Field.
   * @return array
   *   Formatter settings for the specified field using a specific media source type.
   */
  public function getFormatter($managed_field_name): array;

  /**
   * Processes tokens for the asset media type.
   *
   * @param array $tokens
   *   The tokens to process.
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   *
   * @return array
   *   The token replacements.
   */
  public function processTokens(array $tokens, MediaInterface $media): array;

}
