Search by

roilafx / consolevo

Kolya1222

PHP и SQL консоль для Evolution CMS (панель менеджера)

Package info

github.com/Kolya1222/consolevo

Issues

Language:JavaScript

Type:project

pkg:composer/roilafx/consolevo

Statistics

Installs: 34

Dependents: 0

Suggesters: 0

Stars: 1

dev-main 2026-11-11 07:01 UTC

This package is auto-updated.

Last update: 2026-11-11 07:01:17 UTC


README

PHP- и SQL-консоль для Evolution CMS 3.x прямо в панели менеджера: редактор с подсветкой кода (Ace Editor), автодополнением, историей команд и сохранением состояния.

Возможности

  • PHP-консоль — выполнение кода с доступом к Evolution CMS через хелперы evo(), db(), evolutionCMS() (из core/functions/preload.php); внутри консоли те же объекты дополнительно доступны как переменные $modx, $evo, $config, $db, $user. Вывод результата, времени выполнения и расхода памяти.
  • SQL-консоль — выполнение запросов к базе данных с подстановкой префикса таблиц (можно писать FROM site_content, а не FROM evo_site_content), табличный вывод результатов, автодополнение имён таблиц и колонок.
  • Автодополнение для API Evolution CMS — методы ядра подсказываются в реальном виде API: evo()->метод, db()->метод (хелперы core/functions/preload.php; в сниппетах и плагинах тот же объект доступен как $modx), прочие классы — статически Class::метод. Плюс свойства, константы и глобальные функции ядра; данные анализа кэшируются.
  • Подсказки для контроллеров шаблонов (Evolution CE 3.1.30+) — методы EvolutionCMS\TemplateController и ваших контроллеров из core/custom подсказываются как $this->… (addViewData(), getViewData(), ваши getLeftmenu()…); сниппеты avd/avdg (массивная и короткая форма addViewData('leftmenu', 'topmenu')), tcvar/tcset (магические $this->переменная) и view ('tpl' => '@VIEW:partials.item' — Blade-шаблон из /views для DLTemplate).
  • Подсказки полей документа и TV — в PHP-консоли и мини-IDE подсказываются все поля документа (pagetitle, longtitle, introtext… — реальные колонки site_content) и созданные TV-параметры (site_tmplvars, с типом и списком шаблонов). Формат — контекстный, как в ядре: в blade-шаблонах поля и TV подсказываются как ПЕРЕМЕННЫЕ $pagetitle, $имя_tv (ядро передаёт их через view->share(), поэтому {{ $pagetitle }} работает без объявления, а голое {{ pagetitle }} — ошибка «undefined constant»); в PHP-коде — голые имена для ['pagetitle'], $this->pagetitle, evo()->documentObject['pagetitle']. Сниппеты: dobj (evo()->documentObject['…']), mdobj (makeDocumentObject(id)), gtv (getTV()), blv ({{ $… }}).
  • Переменные контроллеров в blade — всё, что передаётся в шаблон через addViewData() (обе формы: массив и короткая addViewData('leftmenu', 'topmenu')), подсказывается в blade как $переменная с указанием источника — класса или трейта и файла. Сканится весь core/custom (включая пакеты вроде custom/packages/shop), так что переменные базового контроллера, наследников и трейтов попадают в подсказки автоматически — в течение минуты после правки (document_cache_ttl).
  • Blade-директивы — полный набор стандартных директив Blade из документации Laravel 8 (@if/@isset/@forelse/@switch/@each/@once/@push/@stack/@dd/@dump/@method/@error…) плюс кастомные Evolution CMS (@evoParser, @evoLang, @makeUrl, @phpthumb…).
  • История команд — сохраняется в localStorage, поиск, фильтры, экспорт в JSON.
  • Настройки редактора — тема, размер и шрифт, перенос строк задаются значком настроек (шестерёнка) прямо в интерфейсе; состояние восстанавливается после перезагрузки страницы. Для централизованной настройки всех консолей — файл editor-config.js, см. Стили Ace: шестерёнка в UI или файл.
  • Мини-IDE — редактирование файлов проекта прямо из менеджера: дерево файлов (views/, core/custom/ и ваши корни; видны и пустые папки — с плашкой «— пусто —», чтобы их можно было наполнить или удалить через ПКМ), вкладки, подсветка PHP/JS/CSS/JSON/Blade, автодополнение API ядра (evo()->…, db()->…, Blade-директивы), Ctrl+S, проверка синтаксиса php -l перед сохранением и автоматические бэкапы. Файлы не в UTF-8 (cp1251) не открываются — чтобы случайно не испортить их сохранением из браузера. Ace Editor и все его режимы/воркеры/сниппеты поставляются локально в assets/plugins/consolevo/ace-editor/ — без CDN.
  • MCP-сервер для AI-агентов — эндпоинт /consolevo/mcp (Model Context Protocol, JSON-RPC 2.0): Claude Desktop / Claude Code / Cursor читают и правят файлы проекта (контроллеры core/custom, blade-шаблоны views/…), ищут по коду, проверяют синтаксис и читают схему данных — с теми же whitelist-корнями, php -l перед записью, бэкапами и аудитом, что у мини-IDE. Протокол реализован без зависимостей (ядро EVO 3.x — Laravel 8, официальные SDK требуют Laravel 11+). Выключен по умолчанию, токены в конфиге. См. MCP-сервер (для AI-агентов).

Требования

  • Evolution CMS 3.x
  • PHP 8.0+

Установка

Из packagist

Выполните команды из директории /core:

  1. Установка пакета
php artisan package:installrequire roilafx/consolevo "*"
  1. Публикация стилей и скриптов
php artisan vendor:publish --provider="roilafx\Consolevo\ConsolevoServiceProvider"

Из репозитория

cd core/packages          # или каталог ваших custom-пакетов
git clone https://github.com/Kolya1222/Consolevo.git consolevo

Подключите автозагрузку пакета в composer.json сайта (если ещё не подключена) и выполните composer dump-autoload:

"autoload": {
    "psr-4": {
        "roilafx\\Consolevo\\": "core/packages/consolevo/src"
    }
}

Опубликуйте ассеты (js/css/шрифты) в assets/plugins/consolevo/ — скопируйте содержимое каталога publishable/assets туда.

Конфигурация

Файл: assets/plugins/consolevo/big_config/consolevo.php (публикуемый конфиг). Значения из него применяются с ближайшей перезагрузки страницы — провайдер читает файл при каждом запросе.

Ключ По умолчанию Описание
use_modx_popup 1 1 — открывать консоль во встроенном modx.popup, 0 — в отдельном окне браузера
tree_button_users [1] Список ID менеджеров, которым видна кнопка консоли в дереве документов
analysis_cache_ttl 600 Время кэширования данных автодополнения (секунды). 0 — без кэша
document_cache_ttl 60 Время кэширования полей документа, TV и переменных контроллеров для подсказок (секунды). Короткое, чтобы новые TV и свежие addViewData быстро появлялись в подсказках. 0 — без кэша
ide_enabled 1 Включить мини-IDE (/consolevo/ide)
ide_readonly 0 Режим только чтения для IDE
ide_roots [] Корни редактируемых файлов: алиас => абсолютный путь. Пусто — views/ + core/custom/ + ассеты пакета assets/plugins/consolevo/ (editor-config.js, стили). НЕпустой список полностью ЗАМЕНЯЕТ дефолтные корни — допишите нужные явно (и custom/packages/shop, и views/). Исключение — корень consolevo: он защищён и добавляется всегда, чтобы конфигом нельзя было закрыть себе доступ к правке самого конфига (иначе после сохранения файл выпадал из дерева, а вкладка с ним больше не сохранялась — «Неизвестный корень: consolevo»). Пример: 'site' => EVO_CORE_PATH . 'vendor/your-vendor/your-site-package/'
ide_backup_count 10 Сколько бэкапов хранить на файл (0 — без бэкапов). Бэкапы: core/storage/consolevo/backups/
ide_max_file_size 1048576 Максимальный размер редактируемого файла, байт
ide_max_files 4000 Лимит файлов в дереве
ide_php_binary '' Путь к PHP CLI для php -l. Пусто — автодетект (PHP_BINARY, php.exe рядом с php-cgi.exe, PATH). Если бинарарь не найден или не запустился — файл сохраняется с предупреждением, сохранение не блокируется. Windows: 'C:/OSPanel/modules/php/PHP-8.2/php.exe' (без кавычек внутри, прямые слэши работают)
ide_respect_upload_files 1 Уважать настройку Evolution CMS upload_files (+upload_images, +upload_media) при создании/переименовании файлов. 0 — проверка отключена, действует только белый список расширений IDE
mcp_enabled 0 Включить MCP-эндпоинт /consolevo/mcp для AI-агентов (Claude Desktop/Code, Cursor…). 0 — выключен, эндпоинт отвечает 404 (безопасный дефолт)
mcp_tokens ['read' => '', 'write' => ''] Токены доступа: read — только чтение, write — чтение + правка файлов. Строка или массив строк на скоуп; пустая строка — скоуп недоступен. Сравнение — hash_equals, пустые значения не матчатся никогда
mcp_audit 1 Журнал вызовов инструментов (одна JSON-строка на вызов): core/storage/consolevo/mcp-audit.log, ротация при 5 МБ. 0 — отключить

Стили Ace: шестерёнка в UI или файл (editor-config.js)

По умолчанию внешний вид редактора настраивается значком настроек (шестерёнка) в интерфейсе IDE и консолей: тема, шрифт, размер, перенос строк. Выбор хранится в браузере (localStorage) и восстанавливается автоматически — ничего править в файлах не нужно.

Файл assets/plugins/consolevo/js/editor-config.js нужен, когда стиль надо задать централизованно — для всех, кто открывает консоли. По умолчанию в нём ничего не зафиксировано; раскомментируйте нужные ключи (правится прямо в мини-IDE: Ctrl+S → обновить страницу, версия ?v= обновит кэш сама):

window.CONSOLEVO_EDITOR_CONFIG = {
    theme: 'monokai',                    // tomorrow_night | monokai | github | chrome
    fontSize: 18,                        // 8–32, px
    fontFamily: 'Monaco, Consolas, monospace', // CSS-список шрифтов (или null)
    wrapMode: null,                      // true | false | null (не фиксировать)
};

Допустимы любые списки через запятую, как в CSS ("'Fira Code', monospace"); fontFamily: null — шрифт по умолчанию пакета (Fira Code → Consolas → Monaco).

Приоритет: файл > настройки UI (localStorage) > значения по умолчанию. Ключ, заданный в файле, фиксируется — в мини-IDE он блокируется с пометкой, откуда взялся. Чтобы вернуть ключ под управление UI — поставьте null или удалите строку. Допустима и полная форма имени темы ('ace/theme/monokai').

MCP-сервер (для AI-агентов)

Эндпоинт POST /consolevo/mcp — Model Context Protocol поверх JSON-RPC 2.0: подключайте Claude Desktop, Claude Code, Cursor или любой другой MCP-клиент — и агент работает с сайтом курируемо: читает и правит контроллеры (custom => core/custom) и blade-шаблоны (views), ищет по коду, проверяет синтаксис, смотрит реальное API ядра и схему данных — вместо сырого shell/FTP.

Протокол реализован вручную без зависимостей (~500 строк): официальные SDK (laravel/mcp и др.) требуют Laravel 11+ и PHP 8.1+, а ядро Evolution CMS 3.x — это Laravel 8 на PHP 8.0.

Инструменты

Инструмент Скоуп Что делает
list_files read Дерево файлов корней IDE (каталоги с /), фильтры root/path
read_file read Содержимое файла корень::путь + метаданные
search_files read grep по файлам корней: путь:строка: текст, режим PCRE опционально
lint_php read php -l без сохранения — проверка до записи
write_file write Перезапись существующего файла: whitelist-корни, php -l, бэкап
create_file write Новый файл/каталог (уважает upload_files ядра)
rename_entry write Переименование в пределах каталога
delete_file write Удаление файла (с бэкапом) / пустого каталога
sql_select read Только чтение из БД (SELECT/SHOW/DESCRIBE/EXPLAIN/WITH, до 200 строк, префикс таблиц подставляется)
evo_api read Карта API ядра (методы evo()/db(), функции, константы) — против галлюцинаций
document_schema read Поля site_content, TV и переменные контроллеров (addViewData) — что доступно в blade

Произвольное выполнение PHP (eval) по MCP не предоставляется намеренно: агент меняет логику правкой файлов, а не исполнением кода на сервере.

Включение

  1. Сгенерируйте токены (минимум 32 байта):

    php -r "echo 'read:  ', bin2hex(random_bytes(32)), PHP_EOL, 'write: ', bin2hex(random_bytes(32)), PHP_EOL;"
  2. Впишите их в конфиг assets/plugins/consolevo/big_config/consolevo.php:

    'mcp_enabled' => 1,
    'mcp_tokens' => [
        'read'  => '...ключ только для чтения...',
        'write' => '...ключ с правом записи...',
    ],
  3. Проверьте curl'ом:

    curl -s https://site.example/consolevo/mcp \
      -H 'Authorization: Bearer <токен>' \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Подключение Claude Desktop / Claude Code

Локальный stdio-релей bin/consolevo-mcp (публикуется в assets/plugins/consolevo/bin/) превращает newline-delimited JSON-RPC из stdin в HTTP-запросы к сайту: локальному клиенту не нужен бутстрап EVO, а весь auth/аудит/лимиты живут на сайте в одном месте. Требуется только PHP CLI 8.0+.

claude_desktop_config.json:

{
  "mcpServers": {
    "consolevo": {
      "command": "php",
      "args": ["/path/to/site/assets/plugins/consolevo/bin/consolevo-mcp"],
      "env": {
        "CONSOLEVO_URL": "https://site.example",
        "CONSOLEVO_TOKEN": "<write-токен>"
      }
    }
  }
}

В Cursor: Settings → MCP → Add server (то же command/args/env). Параметры можно передавать и флагами: --url=, --token=, --timeout= (по умолчанию 300 с). Диагностика релея пишется в stderr, токен не логируется.

Безопасность

  • Выключено по умолчанию — mcp_enabled = 0, эндпоинт отвечает 404.
  • Токены вместо сессии — агент не умеет в куки/CSRF, поэтому аутентификация по Authorization: Bearer (или X-Consolevo-Token), сравнение hash_equals, пустые значения в конфиге не матчатся никогда. Скоупы: read / write.
  • Все гварды мини-IDE переиспользуются — whitelist-корни ide_roots (+ защищённый consolevo), realpath() против traversal/symlink, белый список расширений, php -l перед записью (сломанный PHP не сохранится), бэкап перед каждой записью/переименованием/удалением, ide_readonly тоже действует.
  • SQL — только чтение: SELECT/SHOW/DESCRIBE/EXPLAIN/WITH, один оператор за вызов, INTO OUTFILE и WITH…DELETE блокируются, результат до 200 строк.
  • Аудит каждого вызова — core/storage/consolevo/mcp-audit.log: кто (IP, User-Agent), скоуп, инструмент, аргументы (содержимое — только размер), успех/ошибка, длительность. Ротация при 5 МБ.
  • Троттлинг — 240 запросов/мин на IP (класс ThrottleRequests, без алиасов ядра).
  • Доверие: write-токен ≈ доступ разработчика к файлам проекта. Не давайте его агентам, чьи системные промпты вы не контролируете. Для исследований хватит read-токена — он ничего не меняет.

Маршруты

Все маршруты, кроме MCP, доступны только авторизованным менеджерам (ConsolevoAccess + CSRF). MCP-эндпоинт авторизуется токенами (см. выше) и живёт вне CSRF-группы с троттлингом:

Маршрут Описание
GET /consolevo Главная страница (выбор консоли)
GET /consolevo/php PHP-консоль
POST /consolevo/php/execute Выполнение PHP-кода
GET /consolevo/sql SQL-консоль
POST /consolevo/sql/execute Выполнение SQL-запроса
GET /consolevo/sql/tables Таблицы и структуры для автодополнения
GET /consolevo/analysis/unified-data Данные автодополнения API Evolution CMS
GET /consolevo/analysis/document-data Поля документа (site_content), TV (site_tmplvars) и переменные шаблона из контроллеров (addViewData) для подсказок
GET /consolevo/ide Мини-IDE: редактирование файлов проекта
GET /consolevo/ide/tree Дерево файлов и каталогов корней IDE (включая пустые папки)
GET /consolevo/ide/file Содержимое файла (?path=корень::путь)
POST /consolevo/ide/save Сохранение файла (с php -l и бэкапом)
POST /consolevo/ide/lint Проверка синтаксиса PHP без сохранения
POST /consolevo/ide/create Создание файла/каталога (ПКМ в дереве)
POST /consolevo/ide/rename Переименование файла/каталога
POST /consolevo/ide/delete Удаление файла (с бэкапом) / пустого каталога
POST /consolevo/mcp MCP-эндпоинт для AI-агентов (JSON-RPC 2.0, auth по токену mcp_tokens, троттлинг 240/мин)

⚠️ Безопасность

Консоль выполняет произвольный PHP-код и SQL-запросы — это инструмент разработчика:

  • доступ ограничен авторизацией в менеджере; кнопка в дереве — списком tree_button_users;
  • чёрный список опасных PHP-функций (eval, exec, system…) и SQL-операций (DROP DATABASE…) — это защита от случайных действий, а не от злонамеренных: не давайте доступ к консоли никому, кому не доверяете полностью;
  • SQL-консоль работает с базой сайта напрямую — будьте осторожны с UPDATE/DELETE/DROP без WHERE/бэкапа.
  • Мини-IDE пишет в файлы проекта: редактируются только whitelist-корни (ide_roots), расширения из белого списка, PHP-файлы с синтаксической ошибкой не сохраняются (.blade.php не проверяется — директивы @if/{{ }} не являются валидным PHP), перед каждой записью (в т.ч. переименованием и удалением) создаётся бэкап. Для просмотра без правок включите ide_readonly. Бэкапы хранятся в core/storage/consolevo/backups/.
  • Создание и переименование файлов уважает настройку Evolution CMS upload_files (как «Файловый менеджер» ядра): если расширения нет в списке, IDE покажет подсказку, куда его добавить. Отключается ключом ide_respect_upload_files.
  • Каталоги удаляются только пустые — рекурсивного удаления в IDE нет намеренно.
  • MCP-эндпоинт — выключен по умолчанию, токены сравниваются hash_equals, write-инструменты требуют write-токен, SQL только на чтение, каждый вызов пишется в аудит (core/storage/consolevo/mcp-audit.log), троттлинг 240 запросов/мин. Подробности — раздел MCP-сервер.

Структура проекта

├── composer.json                  # Пакет roilafx/consolevo
├── routes.php                     # Маршруты (защищены middleware; MCP — токены + throttle)
├── plugins/
│   └── plugin.AddConsole.php      # Кнопка консоли в дереве менеджера
├── src/
│   ├── Analyzers/EvoAnalyzer.php  # Анализ ядра CMS для автодополнения
│   ├── Controllers/               # Тонкие контроллеры (только HTTP)
│   ├── Exceptions/                # ConsolevoException
│   ├── Mcp/                       # MCP-сервер: ядро JSON-RPC, реестр, токены, аудит
│   │   └── Tools/                 # Инструменты: FileTools, SqlTools, AnalysisTools
│   ├── Middleware/ConsolevoAccess.php
│   ├── Services/                  # Бизнес-логика (SQL/PHP выполнение, файлы IDE, данные документа)
│   ├── Support/RespondsJson.php   # Единый формат JSON-ответов
│   └── ConsolevoServiceProvider.php
├── tests/McpServerTest.php        # Автономные тесты MCP (php tests/McpServerTest.php)
├── views/                         # Blade-шаблоны (+ ide.blade.php)
└── publishable/assets/plugins/consolevo/
    ├── big_config/consolevo.php   # Публикуемый конфиг
    ├── ace-editor/                # Ace Editor (vendor)
    ├── bin/consolevo-mcp          # stdio-релей для локальных MCP-клиентов
    ├── fontawesome-7.1.0/         # FontAwesome (vendor)
    ├── css/                       # Стили консоли и IDE
    └── js/
        ├── console.js             # Точка входа консолей
        ├── ide.js                 # Точка входа мини-IDE
        ├── editor-config.js       # Стили Ace из файла (тема/шрифт)
        ├── modules/               # ConsoleManager, IdeManager, FileTree, ...
        └── utils/                 # helpers, constants, completion-data, analyze-evo, document-data

Архитектура (кратко)

  • Бэкенд: ServiceProvider → routes → Middleware → Controller → Service. Контроллеры только принимают запрос и формируют JSON-ответ; вся логика (валидация SQL, подстановка префикса, выполнение, форматирование) — в src/Services.
  • Фронтенд: ES-модули без сборки. ConsoleManager — фасад, координирующий модули: ApiClient (запросы), AceEditor (редактор), OutputManager (вывод), StateManager (сохранение состояния), CommandHistory + HistoryModal (история), PreferencesManager (настройки). Общие утилиты — в js/utils/.
  • Мини-IDE: отдельная страница со своими модулями IdeManager (вкладки/сессии Ace/сохранение) и FileTree (дерево/фильтр); переиспользует PreferencesManager и общие хелперы. Безопасность файла — в IdeFileService: whitelist-корни, realpath()-проверка (traversal и symlink наружу невозможны), белый список расширений, лимит размера, php -l перед записью (файл с синтаксической ошибкой не сохраняется), бэкап с ротацией при каждой записи.
  • MCP: McpController (HTTP, токены, throttle) → McpServer (JSON-RPC 2.0, без зависимостей) → ToolRegistry (скоупы) → инструменты. Инструменты НЕ содержат собственных проверок доступа к файлам — весь контроль в переиспользуемом IdeFileService (единая фабрика IdeFileService::fromConfig()), SQL-инструмент — надстройка read-only над SqlConsoleService, контекстные — те же анализаторы с теми же ключами кэша, что у автодополнения. stdio-релей bin/consolevo-mcp — тонкий транспорт без бутстрапа EVO: протокол пишется/читается как есть, вся безопасность на сайте. Если EVO переедет на Laravel 11+ и появится подходящий SDK — меняется только транспорт/ядро, инструменты не трогаются.
  • Запросы выполнения кода не повторяются автоматически при таймауте/ошибке — чтобы не дублировать INSERT/UPDATE на сервере.