<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\file\FileInterface;
use Drupal\media\MediaInterface;

/**
 * Resolves source files from media entity fields.
 *
 * Extracts the file entity or real path from any file field on a
 * media entity.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface SourceFileResolverInterface {

  /**
   * Gets the source file entity from a media entity field.
   *
   * @param \Drupal\media\MediaInterface $entity
   *   The media entity.
   * @param string $fieldName
   *   The field name containing the source file.
   *
   * @return \Drupal\file\FileInterface|null
   *   File entity or NULL if not found.
   */
  #[\NoDiscard]
  public function getSourceFile(MediaInterface $entity, string $fieldName): ?FileInterface;

  /**
   * Gets the real filesystem path of the source file.
   *
   * @param \Drupal\media\MediaInterface $entity
   *   The media entity.
   * @param string $fieldName
   *   The field name containing the source file.
   *
   * @return string|null
   *   Real file path or NULL if not found.
   */
  #[\NoDiscard]
  public function getSourcePath(MediaInterface $entity, string $fieldName): ?string;

  /**
   * Gets source files for multiple media entities in batch.
   *
   * Collects file IDs from all entities and loads them in a single
   * loadMultiple() call instead of N individual loads.
   *
   * @param array<\Drupal\media\MediaInterface> $mediaEntities
   *   Array of media entities.
   * @param array<string> $fieldNames
   *   Field names to check on each entity.
   *
   * @return array<int, \Drupal\file\FileInterface>
   *   Files keyed by media entity ID. Only entities with a valid source
   *   file are included.
   */
  #[\NoDiscard]
  public function getSourceFiles(array $mediaEntities, array $fieldNames): array;

  /**
   * Validates that a file's content matches expected video MIME types.
   *
   * Uses magic bytes (finfo) to detect actual file content type and
   * rejects files that don't match known video/audio MIME types.
   * This prevents polyglot files from reaching FFmpeg.
   *
   * @param \Drupal\file\FileInterface $file
   *   The file entity to validate.
   *
   * @return bool
   *   TRUE if the file content matches a known video/audio MIME type.
   */
  #[\NoDiscard]
  public function validateFileContent(FileInterface $file): bool;

}
