Система¶

Эндпоинты для операций уровня системы, включая информацию, управление кэшем, окружения, журналы, резервные копии, переводы и отчёты.

Информация о системе¶

GET /system/info

Подробная информация о системе: версии Grav и PHP, загруженные расширения, серверное ПО, текущее окружение, установленные плагины и темы, а также структурированная сводка конфигурации PHP (загрузки, память, обработка ошибок, пути, сессии, OPcache, безопасность, локаль). Предназначен для заполнения страницы «Информация о системе» и страниц поддержки в Admin2. Требуется api.system.read.

Ответ

{"data": {"grav_version": "2.1.0", "php_version": "8.3.14", "php_extensions": ["Core", "date", "pcre"], "server_software": "Apache/2.4.58", "environment": "localhost", "plugins": [{"name": "API", "version": "1.0.38", "enabled": true}], "themes": [{"name": "Quark", "version": "2.0.4", "active": true}], "php_config": {"Upload & POST": {"file_uploads": "1", "upload_max_filesize": "64M", "max_file_uploads": "20", "post_max_size": "64M"}}}}

Коды ответов

Для демо-учётных записей server_software и значения путей в php_config (журнал ошибок, open_basedir, временная папка, корень документов, include path, путь сохранения сессий) заменяются на (hidden in demo mode).

Очистка кэша¶

DELETE /cache

Очищает системный кэш. По умолчанию используется область standard (как у bin/grav cache clear), что соответствует типичной кнопке «сбросить кэш». Используйте scope=all, чтобы также удалить кэши изображений и ресурсов. Требуется api.system.write.

Параметры

Ответ

{"data": {"scope": "standard", "message": "Cache cleared successfully (scope: standard).", "details": ["Cleared:  /var/www/grav/cache/*"]}}

Коды ответов

details — список строк результатов по папкам от очистки кэша Grav.

Получение переводов¶

GET /translations/{lang}

Возвращает все строки перевода для языка в виде плоского отображения ключ/значение. Это публичный маршрут: аутентификация не нужна. Ключи, которые язык не переводит, заполняются из английского (en-US), поэтому отображение полно для любого языка.

Параметры

Ответ

{"data": {"lang": "fr-FR", "dir": "ltr", "count": 1868, "checksum": "5d41402abc4b2a76b9719d911017c592", "strings": {"PLUGIN_ADMIN.SAVE": "Enregistrer"}}}

Коды ответов

dir — направление текста (ltr или rtl), а checksum — MD5 возвращённых строк, поэтому клиент может кэшировать отображение и запрашивать его заново только при изменении контрольной суммы. Строки, которые добавляют только выключенные плагины, не включаются.

Проверка доступности¶

GET /ping

Облегчённая проверка работоспособности. Это публичный маршрут: учётные данные не нужны и разрешения не проверяются, поэтому он лишь подтверждает, что API доступен.

Ответ

{"data": {"pong": true}}

Коды ответов

Список окружений¶

GET /system/environments

Выводит окружения, которые можно выбрать в качестве цели записи конфигурации, а также окружение, определённое Grav для этого запроса. Требуется api.system.read.

Ответ

{"data": {"detected": "localhost", "environments": [{"name": "", "label": "Default", "exists": true, "hasOverrides": false}, {"name": "staging.example.com", "label": "staging.example.com", "exists": true, "hasOverrides": true}]}}

Коды ответов

Первый элемент всегда является базовой конфигурацией (user/config) с name: "" и label: "Default"; его hasOverrides всегда false. Каждый остальной элемент — существующая папка user/env/<name>/, причём включаются и устаревшие макеты user/<host>/config/. hasOverrides сообщает, содержит ли окружение какие-либо файлы конфигурации.

Получение журналов¶

GET /system/logs

Читает записи журнала из файла журнала (по умолчанию grav.log) с постраничной разбивкой, фильтрацией по уровню и текстовым поиском. Записи возвращаются сначала новые. Требуется api.system.read; демо-учётные записи получают 403.

Параметры

Ответ

{"data": [{"date": "2026-09-21T10:30:00.123456+00:00", "logger": "grav", "level": "WARNING", "message": "Plugin X deprecated method"}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 150, "total_pages": 8}}, "links": {"self": "/api/v1/system/logs?page=1&per_page=20", "next": "/api/v1/system/logs?page=2&per_page=20", "last": "/api/v1/system/logs?page=8&per_page=20"}}

Коды ответов

Отчёты¶

GET /reports

Возвращает расширяемые плагинами диагностические отчёты. Встроенные отчёты — проверка безопасности (сканирование XSS), Twig в контенте и линтер YAML. Плагины могут добавлять собственные отчёты через событие onApiGenerateReports. Требуется api.reports.read.

Ответ

{
    "data": [
        {
            "id": "security-check",
            "title": "Grav Security Check",
            "provider": "core",
            "component": null,
            "status": "success",
            "message": "Security Scan complete: No issues found.",
            "items": []
        },
        {
            "id": "twig-content",
            "title": "Twig in Content",
            "provider": "core",
            "component": null,
            "status": "success",
            "message": "Twig in Content is disabled. No pages are leaking raw Twig.",
            "meta": { "gate": false, "sandbox": true, "editor_enabled": false, "leak_count": 0, "event_count": 0, "global_request_gated": false, "frontmatter_request_gated": false },
            "items": []
        },
        {
            "id": "yaml-linter",
            "title": "Grav Yaml Linter",
            "provider": "core",
            "component": null,
            "status": "success",
            "message": "YAML Linting: No errors found.",
            "items": []
        },
        {
            "id": "problems",
            "title": "Grav Potential Problems",
            "provider": "problems",
            "component": "problems-report",
            "status": "success",
            "message": "No critical problems detected.",
            "items": [
                {
                    "id": "PHP Minimum Version",
                    "level": "critical",
                    "status": true,
                    "msg": "Your PHP 8.5.4 is greater than the minimum of 8.3.0 required"
                }
            ]
        }
    ]
}

Коды ответов

Структура отчёта¶

Каждый отчёт в массиве ответа содержит:

Встроенные отчёты¶

• Проверка безопасности — сканирует все страницы на потенциальные уязвимости XSS. Элементы содержат route и field для каждой найденной проблемы.
• Twig в контенте (twig-content): показывает, включён ли Twig в контенте страниц и работает ли он в песочнице, какие страницы выводят посетителям необработанные маркеры Twig и какие токены недавно блокировала песочница. В его meta есть gate, sandbox, editor_enabled, leak_count, event_count, global_request_gated и frontmatter_request_gated; элементы — строки с kind: leak и kind: event. Эндпоинты под /reports/twig-content/ работают с этим отчётом.
• Линтер YAML — проверяет все YAML-файлы на синтаксические ошибки. Элементы содержат file и error для каждой найденной проблемы.

Отчёты плагинов¶

Плагины добавляют отчёты, прослушивая событие onApiGenerateReports. Когда отчёт указывает component, фронтенд админки загружает веб-компонент плагина из GET /gpm/plugins/{provider}/report-script/{component}.

Подробности реализации см. в руководстве Интеграция плагинов с API.

Создание резервной копии¶

POST /system/backup

Запускает резервное копирование сайта. Использует встроенный класс Backups Grav, записывает zip-архив с датой в настроенное место хранения резервных копий и возвращает имя файла, путь, размер и метку времени создания. Admin2 использует его для действия «Создать резервную копию» на панели управления. Требуется api.system.backup, так как архивы содержат хеши паролей учётных записей и секреты конфигурации; демо-учётные записи получают 403.

Ответ

{"data": {"filename": "default_site_backup--20260917120000.zip", "path": "/var/www/grav/backup/default_site_backup--20260917120000.zip", "size": 1048576, "date": "2026-09-17T12:00:00+00:00"}}

Коды ответов

Список резервных копий¶

GET /system/backups

Выводит существующие файлы резервных копий (имя файла, название, дата, размер), а также настроенную политику очистки и число настроенных профилей резервного копирования. Требуется api.system.backup; демо-учётные записи получают 403.

Ответ

{"data": {"backups": [{"filename": "default_site_backup--20260917120000.zip", "title": "Default Site Backup", "date": "2026-09-17T12:00:00+00:00", "size": 1048576}], "purge": {"trigger": "space", "max_backups_count": 25, "max_backups_space": 5, "max_backups_time": 365}, "profiles_count": 1}}

Коды ответов

date — метка времени ISO 8601 в том же формате, что возвращает Создание резервной копии. purge — конфигурация сайта backups.purge.

Удаление резервной копии¶

DELETE /system/backups/{filename}

Удаляет zip-архив резервной копии. Имя файла проверяется, чтобы предотвратить обход пути — это должно быть простое базовое имя, оканчивающееся на .zip. Требуется api.system.backup; демо-учётные записи получают 403.

Параметры

Коды ответов

Скачивание резервной копии¶

GET /system/backups/{filename}/download

Передаёт zip-файл резервной копии вызывающей стороне. Возвращает application/zip с заголовком Content-Disposition: attachment. Требуется api.system.backup; демо-учётные записи получают 403.

Параметры

Коды ответов

Отчёт о системе¶

GET /systeminfo

Формирует компактный отчёт о системе: сведения PHP (версия, SAPI, расширения, лимиты памяти и загрузки), версия Grav, свободное и общее место на диске, число плагинов и состояние кэша. Легче, чем /system/info, и предназначен для виджета «Состояние системы» на панели управления, а не для полной страницы информации о системе в Admin2. Требуется api.system.read.

Ответ

{"data": {"php": {"version": "8.3.14", "sapi": "fpm-fcgi", "extensions": ["Core", "date"], "memory_limit": "256M", "max_execution_time": "60", "upload_max_filesize": "64M", "post_max_size": "64M"}, "grav": {"version": "2.1.0", "php_version": "8.3.14"}, "disk": {"free_space": 10737418240, "total_space": 53687091200}, "plugins": {"total": 30, "enabled": 24, "disabled": 6}, "cache": {"enabled": true, "driver": "auto"}}}

Коды ответов

disk.free_space и disk.total_space указаны в байтах или равны false, когда PHP не может их прочитать.

Создание окружения¶

POST /system/environments

Создаёт пустую папку окружения в user/env/<name>/config, которую затем можно выбрать в качестве цели записи конфигурации. Требуется api.config.write.

Параметры

Запрос

{"name": "staging.example.com"}

Ответ

{"data": {"name": "staging.example.com", "label": "staging.example.com", "exists": true, "hasOverrides": false}}

Коды ответов

Удаление окружения¶

DELETE /system/environments/{name}

Удаляет папку окружения user/env/<name>/ и всё её содержимое. Требуется суперадминистратор, так как папка может содержать переопределения system и security, которые вправе записывать только суперадминистратор.

Параметры

Коды ответов

Список файлов журналов¶

GET /system/logs/files

Выводит файлы журналов, которые может открыть просмотрщик журналов админки. Эти имена — единственные значения, которые GET /system/logs и DELETE /system/logs принимают для file. Требуется api.system.read; демо-учётные записи получают 403.

Ответ

{"data": {"files": [{"file": "grav.log", "label": "Grav System Log"}, {"file": "security.log", "label": "Security Log"}, {"file": "email.log", "label": "Email Log"}, {"file": "scheduler.log", "label": "Scheduler Log"}, {"file": "custom-plugin.log", "label": "Custom Plugin Log"}], "default": "grav.log"}}

Коды ответов

Четыре основных журнала всегда выводятся первыми, даже до того, как в них что-то записано. Затем идут любые другие файлы *.log в папке log://, а после них — файлы, которые добавляют плагины через событие onApiLogFiles. Записи дедуплицируются по имени файла.

Очистка журнала¶

DELETE /system/logs

Очищает один из файлов журналов, перечисленных в GET /system/logs/files. Файл усекается, а не удаляется, и на его месте остаётся одна запись о том, кто его очистил. Требуется суперадминистратор; демо-учётные записи получают 403. Вызывает onApiLogCleared.

Параметры

Запрос

{"file": "grav.log"}

Ответ

{"data": {"file": "grav.log", "cleared_bytes": 450507, "message": "Log cleared: grav.log"}}

Коды ответов

Список языков админки¶

GET /admin/languages

Выводит языки, на которых может отображаться сам интерфейс админки, по одному на каждый файл languages/*.yaml, поставляемый плагином Admin2. Это отличается от GET /languages, который перечисляет языки контента сайта. Сортировка по родному названию; пусто, если Admin2 не установлен. Требуется api.system.read.

Ответ

{"data": {"languages": [{"code": "en-US", "name": "English", "native_name": "English", "rtl": false}, {"code": "fr-FR", "name": "French", "native_name": "Français", "rtl": false}]}}

Коды ответов

Разрешение заблокированного токена Twig¶

POST /reports/twig-content/allowlist

Добавляет один токен, который заблокировала песочница Twig для контента страниц, в соответствующий список security.twig_sandbox.allowed_*, сохраняемый в user/config/security.yaml. Недавние события блокировки этого токена удаляются из отчёта «Twig в контенте». Требуется суперадминистратор (ключу API нужно admin.super в его областях действия).

Параметры

Запрос

{"rule": "filter", "token": "markdown"}

Ответ

{"data": {"rule": "filter", "key": "allowed_filters", "value": ["markdown"], "resolved": 2}}

Коды ответов

key — записанный ключ security.twig_sandbox, а value — его полное новое значение: список имён для tag, filter и function или список строк {class, methods} для method и property. resolved — число удалённых записанных событий блокировки. Поставляемые значения по умолчанию живут в коде, поэтому файл содержит только собственные дополнения сайта. Вызывает onApiConfigUpdated с областью security.

Очистка событий Twig в контенте¶

DELETE /reports/twig-content/events

Очищает список недавно заблокированных или вырезанных токенов Twig в контенте, который читают отчёт «Twig в контенте» и баннер редактора страниц. logs/security.log не затрагивается. Требуется api.system.write.

Ответ

{"data": {"cleared": true}}

Коды ответов

Состояние Twig в контенте для страницы¶

GET /reports/twig-content/page

Состояние «Twig в контенте» для одной страницы, используется баннером редактора страниц: покажет ли страница посетителям необработанные маркеры {{ }} / {% %} и какие недавние события блокировки записаны для её маршрута. Требуется api.reports.read.

Параметры

Ответ

{"data": {"route": "/blog/my-first-post", "gate": false, "sandbox": true, "leak": {"route": "/blog/my-first-post", "requested": true, "gate": false, "reason": "gate_off"}, "events": []}}

Коды ответов

gate — это security.twig_content.process_enabled, а sandbox — security.twig_sandbox.enabled. leak равен null, когда на странице нет маркеров Twig, она использует модульный или тематический Twig, её Twig будет отрендерен как обычно или её не удаётся найти (отсутствующая страница не является ошибкой). Его reason равен gate_off, когда общий переключатель сайта выключен, или page_off, когда переключатель включён, но страница не запрашивает обработку Twig. events перечисляет недавние блокировки именно для этого маршрута, сначала новые.

Сканирование Twig в контенте¶

GET /reports/twig-content/scan

Сканирует все страницы (пропуская модульный и тематический Twig) на теги, фильтры и функции Twig в контенте, которые не разрешены текущими списками песочницы, то есть на то, что потребуется контенту до включения общего переключателя. Требуется api.reports.read.

Ответ

{"data": {"tags": {"include": ["/blog/my-first-post"]}, "filters": {"raw": ["/about"]}, "functions": {"source": ["/about", "/contact"]}}}

Коды ответов

Каждый список сопоставляет токен маршрутам, которые его используют. Список без находок приходит как пустой массив ([]), а не как {}. Это текстовое сканирование и приближение; события блокировки в отчёте, записанные во время рендеринга, — надёжный сигнал. Стоимость растёт с числом страниц.

Политика песочницы Twig¶

GET /reports/twig-content/sandbox-policy

Разбивка песочницы Twig для контента страниц только для чтения: для каждого списка — встроенные значения по умолчанию, собственные дополнения сайта allowed_*, его удаления denied_* и итоговый результат. Требуется api.reports.read.

Ответ

{"data": {"enabled": true, "config_access": false, "lists": {"tags": {"defaults": ["if", "for", "set"], "added": [], "denied": [], "effective": ["if", "for", "set"]}, "filters": {"defaults": ["escape", "upper"], "added": ["markdown"], "denied": [], "effective": ["escape", "upper", "markdown"]}, "functions": {"defaults": ["range"], "added": [], "denied": [], "effective": ["range"]}, "methods": {"defaults": {"Grav\\Common\\Page\\Page": ["title", "url"]}, "added": [], "denied": [], "effective": {"Grav\\Common\\Page\\Page": ["title", "url"]}}, "properties": {"defaults": [], "added": [], "denied": [], "effective": []}}, "config_denied_paths": {"defaults": ["plugins", "streams", "security", "backups", "scheduler", "system.cache.redis.password", "system.debugger.token"], "added": [], "effective": ["plugins", "streams", "security", "backups", "scheduler", "system.cache.redis.password", "system.debugger.token"]}}}

Коды ответов

Списки в примере сокращены. enabled — это security.twig_sandbox.enabled, а config_access — security.twig_content.config_access. В methods и properties каждая запись сопоставляет класс разрешённым именам его членов, а пустое отображение приходит как []. config_denied_paths перечисляет пути конфигурации, скрытые от Twig в контенте. Политика строится только из конфигурации; дополнения, которые делают плагины через onBuildTwigSandboxPolicy, в неё не входят.