Workflow for Plugin Development from Scratch: OOP, Lifecycle APIs, and Data Isolation

<?php
/**
 * Plugin Name: Fullstack Agentic Lab Core Engine
 * Plugin URI: https://agenticlab.dev/workflows/wordpress/wf-plugin-development
 * Description: Высокопроизводительный ООП-плагин для платформы Fullstack Agentic Lab (PHP 8.2+, PSR-4, Custom DB Tables, REST API).
 * Version: 1.0.0
 * Requires at least: 6.4
 * Requires PHP: 8.2
 * Author: Artur Yusupov (Fullstack Agentic Lab)
 * Author URI: https://agenticlab.dev
 * License: GPL v2 or later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: agenticlab-core
 * Domain Path: /languages
 *
 * @package AgenticLab\Core
 */

declare(strict_types=1);

namespace AgenticLab\Core;

if (!defined('ABSPATH')) {
    exit;
}

// Константы плагина
define('AGENTIC_CORE_VERSION', '1.0.0');
define('AGENTIC_CORE_FILE', __FILE__);
define('AGENTIC_CORE_DIR', plugin_dir_path(__FILE__));
define('AGENTIC_CORE_URI', plugin_dir_url(__FILE__));

// Проверка версии PHP перед инициализацией
if (version_compare(PHP_VERSION, '8.2.0', '<')) {
    add_action('admin_notices', function (): void {
        echo '<div class="error"><p>' . esc_html__('Плагин Fullstack Agentic Lab Core требует PHP версии 8.2 или выше.', 'agenticlab-core') . '</p></div>';
    });
    return;
}

// 1. Автозагрузчик классов по стандарту PSR-4
spl_autoload_register(function (string $class): void {
    $prefix = 'AgenticLab\\Core\\';
    $base_dir = AGENTIC_CORE_DIR . 'src/';

    $len = strlen($prefix);
    if (strncmp($prefix, $class, $len) !== 0) {
        return;
    }

    $relative_class = substr($class, $len);
    $file = $base_dir . str_replace('\\', '/', $relative_class) . '.php';

    if (file_exists($file)) {
        require_once $file;
    }
});

// 2. Регистрация хука активации
register_activation_hook(__FILE__, function (): void {
    Database\Migrator::migrate();
    
    // Безопасный однократный сброс rewrite rules
    if (!get_option('agenticlab_core_flush_rewrite')) {
        update_option('agenticlab_core_flush_rewrite', true);
    }
});

// 3. Регистрация хука деактивации (только сброс временных данных!)
register_deactivation_hook(__FILE__, function (): void {
    wp_clear_scheduled_hook('agenticlab_core_daily_cron');
    flush_rewrite_rules(false);
});

// 4. Запуск ядра плагина на хуке plugins_loaded
add_action('plugins_loaded', function (): void {
    Plugin::instance()->boot();
});

<?php
/**
 * Database Migration Handler via dbDelta.
 *
 * @package AgenticLab\Core\Database
 */

declare(strict_types=1);

namespace AgenticLab\Core\Database;

if (!defined('ABSPATH')) {
    exit;
}

final class Migrator {

    public static function get_table_name(): string {
        global $wpdb;
        return $wpdb->prefix . 'agenticlab_logs';
    }

    /**
     * Создает или обновляет схему таблицы без потери существующих данных.
     */
    public static function migrate(): void {
        global $wpdb;

        $table_name = self::get_table_name();
        $charset_collate = $wpdb->get_charset_collate();

        // ВАЖНО: Соблюдение строгих правил dbDelta:
        // 1. Каждое поле на отдельной строке.
        // 2. PRIMARY KEY с ДВУМЯ пробелами перед скобкой!
        // 3. Ключевые слова типов полей в ВЕРХНЕМ регистре.
        $sql = "CREATE TABLE {$table_name} (
            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
            user_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
            event_type VARCHAR(64) NOT NULL DEFAULT '',
            payload LONGTEXT NULL,
            created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
            PRIMARY KEY  (id),
            KEY user_id (user_id),
            KEY event_type (event_type)
        ) {$charset_collate};";

        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
        dbDelta($sql);

        update_option('agenticlab_db_version', AGENTIC_CORE_VERSION);
    }
}

<?php
/**
 * Main Plugin Orchestrator.
 *
 * @package AgenticLab\Core
 */

declare(strict_types=1);

namespace AgenticLab\Core;

if (!defined('ABSPATH')) {
    exit;
}

final class Plugin {

    private static ?self $instance = null;
    private bool $booted = false;

    public static function instance(): self {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct() {}

    /**
     * Инициализация компонентов и подписка на события ядра.
     */
    public function boot(): void {
        if ($this->booted) {
            return;
        }
        $this->booted = true;

        add_action('init', [$this, 'on_init']);
        add_action('rest_api_init', [$this, 'on_rest_api_init']);
        add_action('admin_enqueue_scripts', [$this, 'on_admin_assets']);
    }

    public function on_init(): void {
        // Регистрация кастомного типа записи Portfolio
        register_post_type('agentic_portfolio', [
            'labels' => [
                'name'          => esc_html__('Портфолио', 'agenticlab-core'),
                'singular_name' => esc_html__('Проект', 'agenticlab-core'),
            ],
            'public'       => true,
            'has_archive'  => true,
            'show_in_rest' => true, // Включение редактора Gutenberg и REST API
            'supports'     => ['title', 'editor', 'thumbnail', 'excerpt', 'custom-fields'],
            'menu_icon'    => 'dashicons-portfolio',
        ]);

        // Отложенный однократный сброс rewrite rules после активации
        if (get_option('agenticlab_core_flush_rewrite')) {
            delete_option('agenticlab_core_flush_rewrite');
            flush_rewrite_rules(false);
        }
    }

    public function on_rest_api_init(): void {
        register_rest_route('agenticlab/v1', '/health', [
            'methods'             => 'GET',
            'callback'            => function (): array {
                return [
                    'status'    => 'ok',
                    'version'   => AGENTIC_CORE_VERSION,
                    'timestamp' => time(),
                ];
            },
            'permission_callback' => '__return_true',
        ]);
    }

    public function on_admin_assets(): void {
        wp_enqueue_style(
            'agenticlab-admin-css',
            AGENTIC_CORE_URI . 'assets/css/admin.css',
            [],
            AGENTIC_CORE_VERSION
        );
    }
}

<?php
/**
 * Plugin Uninstall Handler.
 * Triggered ONLY when the user clicks 'Delete' in the WordPress admin panel.
 *
 * @package AgenticLab\Core
 */

declare(strict_types=1);

// Защита: прерываем выполнение, если вызов сделан не ядром при деинсталляции
if (!defined('WP_UNINSTALL_PLUGIN')) {
    exit;
}

global $wpdb;

// 1. Безвозвратное удаление кастомной таблицы плагина
$table_name = $wpdb->prefix . 'agenticlab_logs';
$wpdb->query("DROP TABLE IF EXISTS {$table_name}"); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared

// 2. Удаление сохраненных опций из таблицы wp_options
delete_option('agenticlab_db_version');
delete_option('agenticlab_core_flush_rewrite');

// 3. Очистка транзиентов плагина
delete_transient('agenticlab_core_cache');

// 4. Опционально: удаление всех постов типа agentic_portfolio
$posts = get_posts([
    'post_type'   => 'agentic_portfolio',
    'numberposts' => -1,
    'post_status' => 'any',
    'fields'      => 'ids',
]);

foreach ($posts as $post_id) {
    wp_delete_post($post_id, true); // true = принудительное удаление мимо корзины
}