<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Integrations\Multilingual;

/**
 * Resolves multilingual context for object-model and URL-model integrations.
 *
 * Implementations must be deterministic and side-effect free.
 */
interface LanguageResolverInterface
{
    /**
     * Whether the multilingual system is active.
     *
     * @return bool
     */
    public function isActive(): bool;

    /**
     * Returns the language code of the triggering post, or null if unknown.
     *
     * @param int $postId Triggering post ID.
     * @return string|null
     */
    public function getTriggerLanguage(int $postId): ?string;

    /**
     * Resolves target languages for a purge operation.
     *
     * Common context keys:
     * - `trigger_language` (string)
     * - `trigger_post_id` (int)
     * - `trigger_post_type` (string)
     * - `source_post_id` (int)
     * - `source_post_type` (string)
     *
     * @param array<string,mixed> $context Resolver context.
     * @return string[] Language codes.
     */
    public function resolveTargetLanguages(array $context): array;

    /**
     * Maps a source object ID to a language-specific object ID.
     *
     * URL-model resolvers should return the source object ID when object IDs
     * are language-neutral.
     *
     * @param int $sourceId Source object ID.
     * @param string $postType Source object post type.
     * @param string $lang Target language code.
     * @return int|null
     */
    public function mapObjectId(
        int $sourceId,
        string $postType,
        string $lang
    ): ?int;

    /**
     * Maps a permalink into the given language context.
     *
     * @param string $url Absolute URL.
     * @param string $lang Target language code.
     * @return string
     */
    public function mapPermalink(string $url, string $lang): string;

    /**
     * Returns the default (primary) language code for the site.
     *
     * @return string
     */
    public function getDefaultLanguage(): string;

    /**
     * Switches the global language context.
     *
     * Pass a language code to switch to that language, or null to restore
     * the original language context.
     *
     * @param string|null $lang Language code or null.
     * @return void
     */
    public function switchLanguage(?string $lang): void;
}
