<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Integrations\Caching;

/**
 * Cache adapter interface.
 *
 * Adapters abstract the purge operation for a specific caching solution.
 */
interface CacheAdapterInterface
{
    /**
     * Returns a human-readable adapter label.
     *
     * @return string
     */
    public function getLabel(): string;

    /**
     * Returns a unique key for this adapter.
     *
     * @return string
     */
    public function getKey(): string;

    /**
     * Returns whether this adapter can run in the current environment.
     *
     * @return bool
     */
    public function isAvailable(): bool;

    /**
     * Returns whether this adapter supports runtime cache-enabled detection.
     *
     * @return bool
     */
    public function supportsCacheStatusDetection(): bool;

    /**
     * Returns whether baseline frontend caching is currently enabled.
     *
     * Adapters without status-detection support should return a permissive value
     * and let callers consult supportsCacheStatusDetection().
     *
     * @return bool
     */
    public function isCacheEnabled(): bool;

    /**
     * Allows adapters to register hooks (optional).
     *
     * @return void
     */
    public function registerHooks(): void;

    /**
     * Purges the cache for a WordPress object ID (typically a page ID).
     *
     * @param int $postId Post/page ID to purge.
     * @return bool True on success (best-effort).
     */
    public function purgePostId(int $postId): bool;

    /**
     * Purges all cache entries for the active site.
     *
     * @return bool True on success (best-effort).
     */
    public function purgeAll(): bool;
}
