README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Opcache

Объектная обёртка над расширением Zend OPcache: статус, конфигурация, сброс, инвалидация и прогрев кэша байткода, генерация preload-скрипта, проверка здоровья с рекомендациями и ограничение операций каталогами — с типобезопасными value-объектами вместо «сырых» массивов и нулём runtime-зависимостей.

Установка

composer require cloud-castle/opcache

Требуется PHP 8.1+. Расширение Zend OPcache нужно для работы с живым кэшем; сам пакет корректно сообщает о его отсутствии (isAvailable()).

Быстрый старт

<?php

use CloudCastle\Opcache\Opcache;

$opcache = new Opcache();

if (!$opcache->isAvailable()) {
    echo 'Расширение Zend OPcache не загружено';
} elseif ($opcache->isEnabled()) {
    $status = $opcache->status();
    echo $status->hitRate();                        // доля попаданий, %
    echo $status->memory()->freePercentage();       // запас памяти, %
    echo $status->statistics()->oomRestarts();      // перезапуски из-за памяти
    echo $status->jit()->isEnabled() ? 'JIT on' : 'JIT off';

    $opcache->compile('/app/src/Kernel.php');       // прогрев одного файла
    $opcache->invalidate('/app/src/Kernel.php', force: true);
}

// Массовый прогрев каталога с подробным отчётом.
$report = $opcache->warmer()->warmDirectory('/app/src', exclude: ['*/tests/*']);
echo $report->compiledCount();                      // сколько скомпилировано

// Preload-скрипт из 100 самых «горячих» скриптов кэша.
$opcache->preloadGenerator()->fromHotScripts(100)->write('/app/var/preload.php');

// Проверка здоровья: критичные проблемы, предупреждения и советы.
foreach ($opcache->health() as $recommendation) {
    echo $recommendation->severity()->value, ': ', $recommendation->message(), PHP_EOL;
}

Безопасный режим — операции только внутри разрешённых каталогов:

$opcache = Opcache::restrictedTo('/app/src', '/app/var');
$opcache->compile('/etc/passwd');   // SecurityException: путь вне разрешённых каталогов

Возможности

Статус как объекты — status(): память (MemoryUsage), интернированные строки (InternedStrings), статистика с перезапусками (Statistics), JIT (JitInfo), ленивый список скриптов (Script) и выборка «горячих».
Конфигурация целиком — configuration(): все директивы, версия, чёрный список, типизированные сокращения (jitBufferSize(), isCliEnabled()…).
Управление кэшем — reset(), invalidate(), invalidateMany(), compile(), isCached(); выключенный кэш — это исключение, а не тихий false.
Массовый прогрев — warmer(): рекурсивный обход каталогов, fnmatch-фильтры, пропуск уже закэшированного, обратный вызов прогресса и отчёт WarmupReport.
Генерация preload — preloadGenerator(): из «горячих» скриптов кэша, каталогов и ручных списков; атомарная запись, экранирование путей.
Проверка здоровья — health(): 12 правил с настраиваемыми порогами, каждая рекомендация с уровнем важности, кодом и подсказкой по директиве.
Ограничение путей — Opcache::restrictedTo(...): allowlist каталогов с защитой от ../ и симлинков для всех файловых операций и записи preload.
Экспорт — toArray() / JsonSerializable у всех value-объектов: готовые данные для мониторинга и дашбордов.

Коротко

Единственный PHP-пакет, покрывающий весь жизненный цикл OPcache — статус, прогрев, инвалидацию, preload, диагностику и безопасность — без фреймворка, веб-сервера и runtime-зависимостей. Быстрее и легче всех сравниваемых аналогов; единственный его минус — он моложе и менее распространён, чем они.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.3.32, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	native¹	opcache-gui	cachetool²	preloader	laravel-opcache³	laragear-preload³	opcache-json⁴
Типобезопасные value-объекты статуса и конфигурации	✅	❌	❌	❌	❌	❌	❌	❌
Полная статистика (перезапуски, interned strings, JIT)	✅	❌	✅	✅	❌	❌	❌	✅
Список скриптов и выборка «горячих»	✅	❌	✅	✅	✅	❌	✅	✅
Сброс кэша	✅	✅	✅	✅	❌	✅	❌	❌
Инвалидация файла	✅	✅	✅	✅	❌	❌	❌	❌
Массовая инвалидация каталога	✅	❌	❌	❌	❌	❌	❌	❌
Компиляция файла (прогрев)	✅	✅	❌	✅	❌	✅	❌	❌
Рекурсивный прогрев каталога с отчётом	✅	❌	❌	✅	❌	✅	❌	❌
Генерация preload-скрипта	✅	❌	❌	❌	✅	❌	✅	❌
Проверка здоровья с рекомендациями	✅	❌	❌	❌	❌	❌	❌	❌
Ограничение операций каталогами (allowlist)	✅	❌	❌	❌	❌	❌	❌	❌
Экспорт в JSON/массив	✅	❌	✅	✅	❌	✅	❌	✅
Работает в текущем процессе (без веб-сервера)	✅	✅	❌	❌	✅	❌	❌	✅
Не требует фреймворка	✅	✅	✅	✅	✅	❌	❌	✅
Всего	🏆 14	5	6	8	4	4	2	5

2. Безопасность и корректность

Свойство	🏆 CloudCastle	native¹	opcache-gui	cachetool²	preloader	laravel-opcache³	laragear-preload³	opcache-json⁴
Allowlist каталогов + защита от «../» и симлинков	✅	❌	❌	❌	❌	❌	❌	❌
Fail-safe: нарушение безопасности не «глотается» массовыми операциями	✅	❌	❌	❌	❌	❌	❌	❌
Атомарная запись генерируемых файлов (tmp + rename)	✅	❌	❌	❌	❌	❌	❌	❌
Экранирование путей в генерируемом коде	✅	❌	❌	❌	✅	❌	✅	❌
strict_types во всех файлах	✅	❌	❌	❌	❌	❌	✅	❌
Исключения вместо «тихих» false	✅	❌	❌	❌	✅	❌	✅	❌
Не выполняет внешние процессы и сетевые запросы	✅	✅	✅	❌	✅	❌	✅	✅
Ноль runtime-зависимостей	✅	✅	✅	❌	❌	❌	❌	❌
Всего	🏆 8	2	2	0	3	0	4	1

3. Производительность

Снятие статуса и чтение метрик, 3000 операций (лучший из 3 прогонов); cachetool — 20 операций (подпроцесс на вызов).

Решение	Время (мкс/операция)	Итог
native¹	5,74	базовый уровень (не библиотека)
🏆 CloudCastle	14,10	быстрейшее среди библиотек
preloader	1 078	аналог
opcache-gui	1 293	аналог
cachetool²	50 717	аналог

4. Потребление памяти

Фактически занятая память 1500 удержанных снимков статуса (изолированный процесс, вычет baseline); cachetool нормализован с 20 вызовов.

Решение	Память на 1500 снимков (КБ)	Итог
🏆 CloudCastle	1 470	легчайшее среди всех
native¹	5 427	базовый уровень (не библиотека)
cachetool²	17 064	аналог
opcache-gui	56 956	аналог
preloader	170 716	аналог

5. Качество кода

Критерий	🏆 CloudCastle	native¹	opcache-gui	cachetool²	preloader	laravel-opcache³	laragear-preload³	opcache-json⁴
PHPStan max + strict rules в CI	✅	❌	❌	❌	❌	❌	✅	❌
Psalm errorLevel 1 в CI	✅	❌	❌	❌	❌	❌	❌	❌
Мутационное тестирование, MSI 100%	✅	❌	❌	❌	❌	❌	❌	❌
Покрытие тестами 100% строк	✅	❌	❌	❌	❌	❌	✅	❌
Тесты безопасности, нагрузки и утечек памяти	✅	❌	❌	❌	❌	❌	❌	❌
PHPDoc на каждом публичном методе	✅	❌	❌	❌	❌	❌	✅	❌
Активная поддержка (коммиты за последний год)	✅	✅	✅	✅	✅	❌	✅	❌
Всего	🏆 7	1	1	1	1	0	4	0

¹ Нативные вызовы без полноты решения — контекстный базовый уровень. ² cachetool исполняет каждый вызов в отдельном PHP-процессе (его архитектура). ³ Требует Laravel-приложение (appstract — ещё и HTTP-запрос к себе); в замерах не участвует, факты — по документации и коду. ⁴ Заброшен: зависимость domnikl/statsd удалена с GitHub, установка невозможна.

Плюсы, минусы и когда применять

Плюсы. Функциональный суперсет всех сравниваемых аналогов вместе взятых; самый быстрый и самый экономный по памяти путь к статусу кэша среди библиотек; единственный с ограничением операций каталогами, fail-safe-безопасностью и атомарной записью preload; 100 % покрытие строк, MSI 100 %, PHPStan max и Psalm level 1; ноль runtime-зависимостей.

Минусы. Пакет моложе и менее распространён, чем аналоги (меньше загрузок, звёзд и «обкатки» сообществом). Иных известных минусов нет: замеченные недостатки устраняются, а не документируются.

Когда применять.

Деплой и CI/CD — прогрев кэша после выкладки (warmer()), точечная инвалидация изменённых файлов вместо полного сброса.
Продакшен-мониторинг — status()/toArray() в метрики (Prometheus, Zabbix, Grafana), health() в алерты.
Оптимизация запуска — генерация opcache.preload из реальной статистики «горячих» скриптов, а не из угадывания.
Панели администратора — типобезопасные данные для дашборда без встраивания стороннего GUI.
Библиотеки и фреймворки — нулевые зависимости позволяют встраивать пакет в любой стек (Laravel, Symfony, Yii, чистый PHP).

Когда смотреть на альтернативы. Нужен готовый веб-интерфейс «из коробки» — amnuts/opcache-gui; нужно управлять кэшем чужого FPM-пула без кода — CLI-утилита gordalina/cachetool с её FastCGI-адаптером.

Разработка

composer install
composer check        # линтеры + статический анализ + тесты
composer fix          # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci           # полный CI-пайплайн локально
composer test:mutation                    # мутационные тесты (MSI 100 %)
composer docs:build   # сравнительный прогон + генерация таблиц

Полный список команд с описаниями: composer run-script --list.

Документация

Вики (возможности, примеры, архитектура): wiki/docs/ru
Репозиторий: https://gitverse.ru/cloud-castle/opcache
История изменений: CHANGELOG.md
Переход между версиями: UPGRADING.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md
Поддержка: SUPPORT.md

Канонический контент документации ведётся на русском; переводы (en/de/fr/es/it) — заготовки со ссылкой на русский оригинал, а сравнительные таблицы генерируются автогенератором на всех шести языках.

Лицензия