<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\FFmpegCodecPluginManager;
use Drupal\ffmpeg_media\FFmpegOutputPluginManager;
use Drupal\ffmpeg_media\FFmpegProcessorPluginManager;
use Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface;
use Drupal\ffmpeg_media\Plugin\FFmpegOutput\FFmpegOutputInterface;
use Drupal\ffmpeg_media\Plugin\FFmpegProcessor\FFmpegProcessorInterface;

/**
 * Factory for FFmpeg plugin managers and plugin instance creation.
 *
 * Wraps the three FFmpeg plugin managers (Codec, Output, Processor) behind a
 * single service, reducing constructor parameter counts in services that need
 * multiple plugin types.
 *
 * @internal
 */
interface PluginFactoryInterface {

  /**
   * Gets the codec plugin manager.
   *
   * @return \Drupal\ffmpeg_media\FFmpegCodecPluginManager
   *   The codec plugin manager.
   */
  #[\NoDiscard]
  public function getCodecManager(): FFmpegCodecPluginManager;

  /**
   * Gets the output plugin manager.
   *
   * @return \Drupal\ffmpeg_media\FFmpegOutputPluginManager
   *   The output plugin manager.
   */
  #[\NoDiscard]
  public function getOutputManager(): FFmpegOutputPluginManager;

  /**
   * Gets the processor plugin manager.
   *
   * @return \Drupal\ffmpeg_media\FFmpegProcessorPluginManager
   *   The processor plugin manager.
   */
  #[\NoDiscard]
  public function getProcessorManager(): FFmpegProcessorPluginManager;

  /**
   * Creates a codec plugin instance.
   *
   * @param string $pluginId
   *   The codec plugin ID.
   * @param array<string, mixed> $configuration
   *   Optional plugin configuration.
   *
   * @return \Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface
   *   The codec plugin instance.
   *
   * @throws \Drupal\Component\Plugin\Exception\PluginException
   *   If the plugin cannot be created.
   */
  #[\NoDiscard]
  public function createCodecInstance(string $pluginId, array $configuration = []): FFmpegCodecInterface;

  /**
   * Creates an output plugin instance.
   *
   * @param string $pluginId
   *   The output plugin ID.
   * @param array<string, mixed> $configuration
   *   Optional plugin configuration.
   *
   * @return \Drupal\ffmpeg_media\Plugin\FFmpegOutput\FFmpegOutputInterface
   *   The output plugin instance.
   *
   * @throws \Drupal\Component\Plugin\Exception\PluginException
   *   If the plugin cannot be created.
   */
  #[\NoDiscard]
  public function createOutputInstance(string $pluginId, array $configuration = []): FFmpegOutputInterface;

  /**
   * Creates a processor plugin instance.
   *
   * @param string $pluginId
   *   The processor plugin ID.
   * @param array<string, mixed> $configuration
   *   Optional plugin configuration.
   *
   * @return \Drupal\ffmpeg_media\Plugin\FFmpegProcessor\FFmpegProcessorInterface
   *   The processor plugin instance.
   *
   * @throws \Drupal\Component\Plugin\Exception\PluginException
   *   If the plugin cannot be created.
   */
  #[\NoDiscard]
  public function createProcessorInstance(string $pluginId, array $configuration = []): FFmpegProcessorInterface;

}
