<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\ConversionContext;
use Drupal\media\MediaInterface;

/**
 * Resolves conversion settings from EntityViewDisplay formatter configuration.
 *
 * Scans the 'default' view mode for ffmpeg formatters and extracts
 * auto_convert and conversion_profile settings.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface FormatterSettingsResolverInterface {

  /**
   * Gets all conversion contexts for a media entity.
   *
   * Scans the default EntityViewDisplay for the entity's bundle and
   * returns a ConversionContext for each field using an ffmpeg formatter.
   *
   * @param \Drupal\media\MediaInterface $entity
   *   The media entity.
   *
   * @return array<\Drupal\ffmpeg_media\ValueObject\ConversionContext>
   *   Array of conversion contexts (one per configured formatter field).
   */
  #[\NoDiscard]
  public function getContextsForEntity(MediaInterface $entity): array;

  /**
   * Gets the conversion context for a specific field on a media entity.
   *
   * @param \Drupal\media\MediaInterface $entity
   *   The media entity.
   * @param string $fieldName
   *   The field name to check.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionContext|null
   *   Conversion context or NULL if field does not use an ffmpeg formatter.
   */
  #[\NoDiscard]
  public function getContextForField(MediaInterface $entity, string $fieldName): ?ConversionContext;

  /**
   * Gets the preferred conversion context for a media entity.
   *
   * Prefers the media source field context when multiple ffmpeg-managed
   * fields are configured on the same bundle. Falls back to the first
   * configured context when no source field mapping is present.
   *
   * @param \Drupal\media\MediaInterface $entity
   *   The media entity.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionContext|null
   *   Preferred conversion context or NULL when none are configured.
   */
  #[\NoDiscard]
  public function getPreferredContextForEntity(MediaInterface $entity): ?ConversionContext;

  /**
   * Gets all conversion contexts across all configured bundles and fields.
   *
   * Scans all media bundle EntityViewDisplays for ffmpeg formatters.
   *
   * @return array<\Drupal\ffmpeg_media\ValueObject\ConversionContext>
   *   Array of all configured conversion contexts.
   */
  #[\NoDiscard]
  public function getAllContexts(): array;

  /**
   * Checks if any ffmpeg formatter is configured anywhere.
   *
   * @return bool
   *   TRUE if at least one ffmpeg formatter is configured.
   */
  #[\NoDiscard]
  public function hasAnyConfiguration(): bool;

  /**
   * Resets per-request caches.
   *
   * Call after modifying EntityViewDisplay formatter settings mid-request
   * (e.g., in kernel tests).
   */
  public function resetCache(): void;

}
