<?php

/**
 * Interface voor plugin-API-objecten.
 *
 * Zowel CMSAPI (front-end) als AdminPluginAPI (admin) implementeren deze interface.
 *
 * @since 2.6.4
 */
interface PluginAPIInterface
{
    /**
     * Haal een configuratiewaarde op via dot-notatie.
     *
     * @since 2.6.4
     *
     * @param string $key     Configuratie-sleutel in dot-notatie (bijv. 'language.default').
     * @param mixed  $default Standaardwaarde indien de sleutel niet bestaat.
     * @return mixed De gevonden waarde of $default indien niet gevonden.
     */
    public function getConfig(string $key, $default = null);

    /**
     * Haal de project-rootdirectory op (absoluut, genormaliseerd).
     *
     * @since 2.6.4
     *
     * @return string Absoluut pad naar de project-root.
     */
    public function getProjectRoot(): string;

    /**
     * Haal het pad naar de contentdirectory op (absoluut, genormaliseerd).
     *
     * Bij een relatieve configuratiewaarde wordt deze afgezet tegen de project-root.
     *
     * @since 2.6.4
     *
     * @return string Absoluut pad naar de contentdirectory.
     */
    public function getContentDir(): string;

    /**
     * Haal het pad naar de pluginsdirectory op (absoluut, genormaliseerd).
     *
     * @since 2.6.4
     *
     * @return string Absoluut pad naar de pluginsdirectory.
     */
    public function getPluginsDir(): string;

    /**
     * Haal de versie-informatie uit version.php op als associatieve array.
     *
     * Bevat altijd minimaal de sleutel 'version'.
     *
     * @since 2.6.4
     *
     * @return array<string,mixed> Versie-informatie met minimaal de sleutel 'version'.
     */
    public function getVersionInfo(): array;

    /**
     * Haal de vertalingen voor een plugin op in de huidige context.
     *
     * System-plugins resolven tegen de admin-taal; content-plugins tegen de
     * huidige content-taal. De implementatie regelt de fallback naar de
     * default_language van de plugin.
     *
     * @since 2.6.4
     *
     * @param string      $pluginName Plugin-directorynaam.
     * @param string|null $lang       Optionele override-taal.
     * @return array<string,string> Vertalingen als [key => value].
     */
    public function getPluginTranslations(string $pluginName, ?string $lang = null): array;

    /**
     * Vertaal een enkele sleutel voor een plugin in de huidige context.
     *
     * @since 2.6.4
     *
     * @param string      $key        Vertaalsleutel.
     * @param string      $pluginName Plugin-directorynaam.
     * @param string|null $lang       Optionele override-taal.
     * @return string Vertaalde string, of $key indien niet gevonden.
     */
    public function t(string $key, string $pluginName, ?string $lang = null): string;
}