<?php
declare(strict_types=1);

namespace App\Core;

/**
 * Every plugin must implement this interface.
 *
 * Plugin directory structure:
 *   plugins/
 *     {slug}/
 *       plugin.json   ← manifest (required)
 *       Plugin.php    ← main class (required)
 *       Controllers/  ← optional
 *       Views/        ← optional
 *       migrations/   ← optional SQL files
 *       assets/       ← optional CSS/JS
 *
 * plugin.json keys:
 *   id          string  unique slug (matches folder name)
 *   name        string  human-readable name (Persian/English)
 *   version     string  semver e.g. "1.0.0"
 *   description string  short description
 *   author      string  developer name
 *   class       string  FQCN of the Plugin class e.g. "Plugins\\MyPlugin\\Plugin"
 *   requires    string  minimum core version required e.g. "1.2.0"
 */
interface PluginInterface
{
    /**
     * Called on every request when the plugin is active.
     * Register routes (via Hooks::addFilter('routes', ...)),
     * admin sidebar items (Hooks::addFilter('admin_sidebar', ...)),
     * or any other integration here.
     */
    public function boot(): void;

    /**
     * Called once when the admin activates the plugin.
     * Create database tables, seed data, etc.
     */
    public function activate(): void;

    /**
     * Called when the admin deactivates (but does NOT delete) the plugin.
     * Safe to clean up caches, scheduled tasks, etc.
     * Do NOT drop tables here — that is for uninstall().
     */
    public function deactivate(): void;

    /**
     * Called when the admin permanently deletes the plugin.
     * Drop all plugin-created tables, remove all stored data.
     */
    public function uninstall(): void;
}
