Конфигурация¶
Все файлы конфигурации Grav написаны в синтаксисе YAML и имеют расширение .yaml. YAML очень интуитивен, поэтому его легко и читать, и писать, однако вы можете заглянуть на страницу YAML в главе «Для продвинутых», чтобы полностью понять доступный синтаксис.
Примечание
Совет: см. Безопасность > Конфигурация, чтобы быстро узнать, как защитить и оптимизировать вашу рабочую версию сайта.
Системная конфигурация¶
Grav старается максимально упростить всё для пользователя, и это касается конфигурации. Grav поставляется с разумными параметрами по умолчанию, которые содержатся в файле system/config/system.yaml.
Однако этот файл никогда не следует изменять. Вместо этого любые нужные изменения конфигурации должны храниться в файле user/config/system.yaml. Любой параметр в этом файле с той же структурой и именованием переопределит параметр, заданный в файле системной конфигурации по умолчанию.
Совет
В общем случае вам НИКОГДА не следует что-либо менять в папке system/. Всё, что делает пользователь (создание контента, установка плагинов, редактирование конфигурации и т. д.), должно выполняться в папке user/. Так проще обновляться, а все ваши изменения находятся в одном месте для резервного копирования, синхронизации и т. д.
Вот переменные, которые находятся в файле system/config/system.yaml по умолчанию:
Основные параметры¶
Эти параметры конфигурации не входят в собственные дочерние разделы. Это общие параметры, которые влияют на работу сайта, его часовой пояс и базовый URL.
| Свойство | Описание |
|---|---|
| absolute_urls: | Абсолютные или относительные URL для base_url |
| timezone: | Допустимые значения можно найти здесь |
| default_locale: | Локаль по умолчанию (по умолчанию — системная) |
| param_sep: | Используется для параметров Grav в URL. Не меняйте это, если не знаете, что делаете. Grav автоматически устанавливает ; для пользователей, запускающих веб-сервер Apache в Windows |
| wrapped_site: | Для тем и плагинов, чтобы знать, обёрнут ли Grav другой платформой. Может быть true или false |
| reverse_proxy_setup: | Работа через обратный прокси, когда порты веб-сервера отличаются от портов прокси. Может быть true или false |
| force_ssl: | Если включено, Grav принудительно доступен через HTTPS (ПРИМЕЧАНИЕ: не идеальное решение). Может быть true или false |
| force_lowercase_urls: | Если вы хотите поддерживать URL со смешанным регистром, установите false |
| custom_base_url: | Установить base_url вручную здесь |
| username_regex: | Только строчные символы, цифры, дефисы и подчёркивания. От 3 до 16 символов |
| pwd_regex: | Как минимум одна цифра, одна заглавная и одна строчная буква, не менее 8 символов |
| intl_enabled: | Специальная логика для расширения PHP International (mod_intl) |
| http_x_forwarded: | Параметры конфигурации для различных заголовков HTTP_X_FORWARD (Grav 1.7.0+) |
Языки¶
Область Языки в файле задаёт языковые настройки сайта. Сюда входит, какие языки поддерживаются, указание языка по умолчанию в URL и переводы. Вот разбор области Языки файла системной конфигурации:
| Свойство | Описание |
|---|---|
| supported: | Список поддерживаемых языков. Например: [en, fr, de] |
| default_lang: | По умолчанию — первый поддерживаемый язык. Должен быть одним из поддерживаемых языков |
| include_default_lang: | Включать префикс языка по умолчанию во все URL. Может быть true или false |
| include_default_lang_file_extension: | Если включено, при сохранении страницы язык по умолчанию будет добавляться к расширению файла (например, .en.md). Отключите, чтобы язык по умолчанию использовал расширение .md. Может быть true или false (Grav 1.7.0+) |
| pages_fallback_only: | Искать содержимое страниц только через поддерживаемые языки. Может быть true или false |
| translations: | Включать переводы по умолчанию. Может быть true или false |
| translations_fallback: | Переходить к поддерживаемым переводам, если активного языка не существует. Может быть true или false |
| session_store_active: | Хранить активный язык в сессии. Может быть true или false |
| http_accept_language: | Пытаться установить язык на основе заголовка http_accept_language в браузере. Может быть true или false |
| override_locale: | Переопределять локаль по умолчанию или системную на локаль конкретного языка. Может быть true или false |
| content_fallback: | По умолчанию, если контент не переведён, Grav отображает его на языке по умолчанию. Используйте этот параметр, чтобы переопределить такое поведение для каждого языка отдельно. (Grav 1.7.0+) |
Главная¶
Раздел Главная — это место, где задаётся маршрут по умолчанию к домашней странице сайта. Также можно скрыть маршрут главной в URL.
| Свойство | Описание |
|---|---|
| alias: | Путь по умолчанию для главной, например: /home или / |
| hide_in_urls: | Скрыть маршрут главной в URL. Может быть true или false |
Страницы¶
Раздел Страницы файла system/config/system.yaml — это место, где задаётся множество основных параметров, связанных с темой. Например, здесь задаётся тема, используемая для рендеринга сайта, порядок страниц, параметры обработки Twig и Markdown по умолчанию и многое другое. Здесь принимается большинство решений, влияющих на то, как отображаются ваши страницы.
| Свойство | Описание |
|---|---|
| type: | Экспериментальный параметр для включения Flex Pages на фронтенде. Используйте flex для включения, иначе regular. По умолчанию — regular (Grav 1.7+) |
| theme: | Здесь задаётся тема по умолчанию. По умолчанию — quark |
| order: | |
| ... by: | Сортировать страницы по default, alpha или date |
| ... dir: | Направление сортировки по умолчанию: asc или desc |
| list: | |
| ... count: | Количество элементов на странице по умолчанию |
| dateformat: | |
| ... default: | Формат даты по умолчанию, который Grav ожидает в поле date: |
| ... short: | Краткий формат даты. Пример: 'jS M Y' |
| ... long: | Длинный формат даты. Пример: 'F jS \a\t g:ia' |
| publish_dates: | Автоматически публиковать/снимать с публикации по датам. Может быть true или false |
| process: | |
| ... markdown: | Включать или отключать обработку markdown на фронтенде. Может быть true или false |
| ... twig: | Включать или отключать обработку twig на фронтенде. Может быть true или false. Grav 2.0: Twig в содержимом страницы также контролируется переключателем безопасности и выполняется в песочнице; одного флага process.twig теперь недостаточно для рендеринга Twig в контенте. См. Twig в контенте |
| twig_first: | Обрабатывать Twig перед markdown, когда на странице включена обработка обоих. Может быть true или false |
| never_cache_twig: | Включение этого параметра позволит добавить логику обработки, которая может динамически меняться при каждой загрузке страницы, вместо кэширования результатов для каждой загрузки. Может быть включено/отключено на уровне всего сайта в system.yaml или для конкретной страницы. Может быть true или false |
| events: | |
| ... page: | Включить события уровня страницы. Может быть true или false |
| ... twig: | Включить события уровня Twig. Может быть true или false |
| markdown: | |
| ... extra: | Включить поддержку Markdown Extra (по умолчанию — GitHub-flavored Markdown (GFM)). Может быть true или false |
| ... auto_line_breaks: | Включить автоматические переносы строк. Может быть true или false |
| ... auto_url_links: | Включить автоматические HTML-ссылки. Может быть true или false |
| ... escape_markup: | Экранировать теги разметки в сущности. Может быть true или false |
| ... special_chars: | Список специальных символов для автоматического преобразования в сущности. Каждый символ занимает строку ниже этой переменной. Пример: '>': 'gt' |
| ... valid_link_attributes: | Допустимые атрибуты, передаваемые через ссылки markdown (Grav 1.7+) |
| types: | Список допустимых типов страниц. Например: [txt,xml,html,htm,json,rss,atom] |
| markdown_output: | Отдавать любую страницу как Markdown для ИИ-агентов по адресу <route>.md или при Accept: text/markdown. См. Markdown для ИИ-агентов (Grav 2.1+) |
| ... enabled: | Включить фичу. Может быть true или false |
| ... frontmatter: | Начинать каждый документ с блока YAML с заголовком, URL, датой, описанием и таксономией |
| ... links: | Завершать каждый документ ссылками на родительскую, соседние и дочерние страницы |
| ... max_links: | Максимум дочерних страниц, перечисляемых в этом разделе. 0 — перечислять все |
| ... absolute_urls: | Преобразовывать относительные к корню ссылки и изображения в абсолютные URL |
| ... token_header: | Отправлять заголовок X-Markdown-Tokens с приблизительным количеством токенов |
| append_url_extension: | Добавлять расширение страницы в URL страниц (например, .html даёт /path/page.html) |
| expires: | Время истечения срока действия страницы в секундах (604800 секунд = 7 дней) (также возможно no cache) |
| cache_control: | Можно оставить пустым, чтобы не задавать, или указать допустимое текстовое значение cache-control |
| last_modified: | Устанавливать заголовок даты последнего изменения на основе временной метки изменения файла. Может быть true или false |
| etag: | Устанавливать тег заголовка etag. Может быть true или false |
| vary_accept_encoding: | Добавлять заголовок Vary: Accept-Encoding. Может быть true или false |
| redirect_default_route: | Автоматически перенаправлять на маршрут страницы по умолчанию. Может быть true или false |
| redirect_default_code: | Код по умолчанию для перенаправлений. Например: 302 |
| redirect_trailing_slash: | Обрабатывать автоматически или перенаправлять с кодом 302 URL с завершающей косой чертой |
| ignore_files: | Файлы, которые следует игнорировать при обработке страниц. Пример: [.DS_Store] |
| ignore_folders: | Папки, которые следует игнорировать при обработке страниц. Пример: [.git, .idea] |
| ignore_hidden: | Игнорировать все скрытые файлы и папки. Может быть true или false |
| hide_empty_folders: | Скрывать папку, если в ней нет файла .md. Может быть true или false |
| url_taxonomy_filters: | Включить автоматические фильтры таксономии на основе URL для коллекций страниц. Может быть true или false |
| frontmatter: | |
| ... process_twig: | Нужно ли обрабатывать метаданные страницы для замены переменных Twig? Может быть true или false |
| ... ignore_fields: | Поля, которые могут содержать переменные Twig и не должны обрабатываться. Пример: ['form','forms'] |
Кэш¶
Раздел Кэш — это место, где можно настроить параметры кэширования сайта. Вы можете включить или отключить кэширование, выбрать метод и многое другое.
| Свойство | Описание |
|---|---|
| enabled: | Установите true, чтобы включить кэширование. Может быть true или false |
| check: | |
| ... method: | Метод проверки изменений на страницах. Варианты: file, folder, hash и none. Подробнее |
| driver: | Выберите драйвер кэша. Варианты: auto, file, apcu, redis, memcache и wincache |
| prefix: | Строка префикса кэша (предотвращает конфликты кэша). Пример: g |
| purge_at: | Планировщик: как часто очищать старый кэш, используя синтаксис cron at |
| clear_at: | Планировщик: как часто очищать кэш, используя синтаксис cron at |
| clear_job_type: | Тип очистки при выполнении задания плановой очистки. Варианты: standard | all |
| clear_images_by_default: | По умолчанию Grav не включает обработанные изображения при очистке кэша; это можно включить, установив true |
| cli_compatibility: | Гарантирует использование только постоянных драйверов (file, redis, memcache и т. д.) |
| lifetime: | Время жизни кэшированных данных в секундах (0 = бесконечно). 604800 — это 7 дней |
| gzip: | Сжимать вывод страницы с помощью GZip. Может быть true или false |
| allow_webserver_gzip: | Этот параметр изменит заголовок на Content-Encoding: identity, позволяя веб-серверу более надёжно устанавливать gzip, хотя это обычно ломает внепроцессную возможность onShutDown(). Событие всё равно выполнится, но уже не вне процесса и может задержать страницу до завершения события |
| redis: | |
| ... socket: | Путь к файлу сокета redis |
| ... password: | Необязательный пароль |
| ... database: | Необязательный идентификатор базы данных |
Twig¶
Раздел Twig даёт вам быстрый набор инструментов для настройки Twig на сайте: отладки, кэширования и оптимизации.
| Свойство | Описание |
|---|---|
| cache: | Установите true, чтобы включить кэширование Twig. Может быть true или false |
| debug: | Включить отладку Twig. Может быть true или false |
| auto_reload: | Обновлять кэш при изменениях. Может быть true или false |
| autoescape: | Автоматическое экранирование переменных Twig. Может быть true или false |
| undefined_functions: | Разрешить неопределённые функции. Может быть true или false |
| undefined_filters: | Разрешить неопределённые фильтры. Может быть true или false |
| umask_fix: | По умолчанию Twig создаёт кэшированные файлы с правами 755; этот параметр меняет их на 775. Может быть true или false |
Ресурсы¶
Раздел Ресурсы позволяет настроить параметры, связанные с менеджером ресурсов (JS, CSS).
| Свойство | Описание |
|---|---|
| css_pipeline: | Конвейер CSS — это объединение нескольких CSS-ресурсов в один файл. Может быть true или false |
| css_pipeline_include_externals: | По умолчанию включать внешние URL в конвейер. Может быть true или false |
| css_pipeline_before_excludes: | Рендерить конвейер перед любыми исключёнными файлами. Может быть true или false |
| css_minify: | Минифицировать CSS во время объединения в конвейер. Может быть true или false |
| css_minify_windows: | Переопределение минификации для платформ Windows. По умолчанию false из-за ThreadStackSize. Может быть true или false |
| css_rewrite: | Переписывать относительные URL в CSS во время объединения в конвейер. Может быть true или false |
| js_pipeline: | Конвейер JS — это объединение нескольких JS-ресурсов в один файл. Может быть true или false |
| js_pipeline_include_externals: | По умолчанию включать внешние URL в конвейер. Может быть true или false |
| js_pipeline_before_excludes: | Рендерить конвейер перед любыми исключёнными файлами. Может быть true или false |
| js_module_pipeline | Конвейер JS-модулей — это объединение нескольких ресурсов JS-модулей в один файл. Может быть true или false |
| js_module_pipeline_include_externals | По умолчанию включать внешние URL в конвейер. Может быть true или false |
| js_module_pipeline_before_excludes | Рендерить конвейер перед любыми исключёнными файлами. Может быть true или false |
| js_minify: | Минифицировать JS во время объединения в конвейер. Может быть true или false |
| enable_asset_timestamp: | Включить временные метки ресурсов. Может быть true или false |
| enable_asset_sri: | Включить SRI для ресурсов. Может быть true или false |
| collections: | Содержит коллекции, обозначенные как подэлементы. Например: jquery: system://assets/jquery/jquery-3.x.min.js. Подробнее об этом |
Ошибки¶
Раздел Ошибки определяет, как Grav отображает ошибки и ведёт их журнал.
| Свойство | Описание |
|---|---|
| display: | Определяет, как отображаются ошибки. Введите 1 для полной трассировки, 0 для простой ошибки или -1 для системной ошибки |
| log: | Записывать ошибки в папку /logs. Может быть true или false |
Журнал¶
Раздел Журнал позволяет настроить альтернативные возможности ведения журнала для Grav.
| Свойство | Описание |
|---|---|
| handler: | Обработчик журнала. Сейчас поддерживаются: file | syslog |
| syslog: | |
| ... facility: | Категория (facility) для syslog |
Отладчик¶
Раздел Отладчик даёт возможность активировать отладчик Grav — полезный инструмент во время разработки.
| Свойство | Описание |
|---|---|
| enabled: | Включить отладчик Grav и следующие параметры. Может быть true или false |
| provider: | Провайдер отладчика: можно установить debugbar или clockwork (Grav 1.7+) |
| censored: | Скрывать потенциально конфиденциальную информацию (POST-параметры, cookies, файлы, конфигурацию и большинство данных массивов/объектов в сообщениях журнала). Может быть true или false (Grav 1.7+) |
| token: | Общий секрет, который удалённый клиент должен отправить, чтобы прочитать данные профилировщика /__clockwork/. Пустое значение означает, что данные можно прочитать только с самого сервера. См. Отладка (Grav 2.0.22+) |
| shutdown: | |
| ... close_connection: | Закрыть соединение перед вызовом onShutdown(). false для отладки |
Изображения¶
Раздел Изображения позволяет задать качество изображений по умолчанию, с которым они пересэмплируются, а также управлять кэшированием изображений и фичами отладки.
| Свойство | Описание |
|---|---|
| default_image_quality: | Качество изображения по умолчанию при пересэмплировании. Например: 85 = 85 % |
| cache_all: | Кэшировать все изображения по умолчанию. Может быть true или false |
| cache_perms: | Должно быть в кавычках! Права папки кэша по умолчанию. Обычно '0755' или '0775' |
| debug: | Показывать поверх изображений наложение с указанием глубины цвета, например при работе с retina. Может быть true или false |
| auto_fix_orientation: | Пытаться автоматически исправлять изображения, загруженные с нестандартным поворотом |
| seofriendly: | SEO-дружественные имена обработанных изображений |
| cls: | Cumulative Layout Shift (совокупный сдвиг макета). Подробнее |
| ... auto_sizes: | Автоматически добавлять изображению height/width |
| ... aspect_ratio: | Резервировать место с помощью стиля соотношения сторон |
| ... retina_scale: | Масштаб для корректировки автоматических размеров при лучшей поддержке разрешений HiDPI |
| defaults: | (Grav 1.7+) |
| ... loading: | Позволить браузеру выбрать: auto, lazy или eager (Grav 1.7+) |
Медиафайлы¶
Раздел Медиафайлы содержит параметры конфигурации, связанные с обработкой медиафайлов. Сюда входит отображение временных меток, размер загрузки и многое другое.
| Свойство | Описание |
|---|---|
| enable_media_timestamp: | Включить временные метки медиафайлов |
| unsupported_inline_types: | Массив поддерживаемых типов медиафайлов, которые нужно пытаться отображать встроенно. Эти типы файлов указываются в квадратных скобках [] |
| allowed_fallback_types: | Массив разрешённых типов медиафайлов, найденных при доступе через маршрут страницы. Эти типы файлов указываются в квадратных скобках [] |
| auto_metadata_exif: | Автоматически создавать файлы метаданных из данных Exif, где это возможно |
Сессия¶
Эти параметры определяют свойства сессии для вашего сайта.
| Свойство | Описание |
|---|---|
| enabled: | Включить поддержку сессий. Может быть true или false |
| initialize: | Инициализировать сессию из Grav (если false, плагин должен запускать сессию сам) |
| timeout: | Тайм-аут в секундах. Например: 1800 |
| name: | Префикс имени cookie сессии. Используйте только буквы, цифры, дефисы и подчёркивания. Не используйте точки в имени сессии. Например: grav-site |
| uniqueness: | Должны ли сессии основываться на path или на security.salt |
| secure: | Установить защиту сессии. Если true, это означает, что передача этого cookie должна осуществляться по шифрованному каналу. Включайте это только на сайтах, работающих исключительно по HTTPS. Может быть true или false |
| httponly: | Установить для сессии HTTP only. Если true, это означает, что cookies должны использоваться только по HTTP, а изменение через JavaScript запрещено. Может быть true или false |
| samesite: | Установить SameSite для сессии. Возможные значения: Lax, Strict и None. См. здесь |
| domain: | Домен сессии, используемый в ответах. Используйте только если вы переписываете домен сайта, например в контейнере Docker. |
| path: | Путь сессии, используемый в ответах. Используйте только если вы переписываете подпапку сайта, например в контейнере Docker. |
GPM¶
Параметры в разделе GPM управляют GPM Grav (менеджером пакетов Grav). Например, можно ограничить GPM использованием официальных источников и выбрать метод, который GPM использует для получения пакетов. Также можно выбирать между стабильными и тестовыми релизами и настроить URL прокси.
| Свойство | Описание |
|---|---|
| releases: | Установите stable или testing, чтобы определить, хотите ли вы обновляться до последней стабильной или тестовой сборки |
| proxy_url: | Настроить URL прокси вручную для GPM. Например: 127.0.0.1:3128 |
| method: | Одно из значений: 'curl', 'fopen' или 'auto'. 'auto' сначала попробует fopen, а если недоступно — cURL |
| verify_peer: | В некоторых системах (в основном Windows) GPM не может подключиться, потому что SSL-сертификат не удаётся проверить. Отключение этого параметра может помочь |
| official_gpm_only: | По умолчанию прямая установка через GPM разрешает URL только через официальный прокси GPM для обеспечения безопасности; отключите это, чтобы разрешить другие источники |
Учётные записи¶
Параметры учётных записей позволяют попробовать новые экспериментальные Flex Users. По сути это означает, что пользователи хранятся как Flex-объекты, что даёт больше возможностей и производительности.
| Свойство | Описание |
|---|---|
| type: | Тип учётной записи: regular или flex |
| storage: | Тип хранилища Flex: file или folder |
Flex¶
Параметры кэша Flex-объектов появились в Grav 1.7. Это параметры по умолчанию для всех типов Flex, но их можно переопределить для каждой директории Flex.
| Свойство | Описание |
|---|---|
| cache: | (Grav 1.7+) |
| ... index: | (Grav 1.7+) |
| ... ... enabled: | Установите true, чтобы включить кэширование индекса Flex. Используется для кэширования временных меток в файлах (Grav 1.7+) |
| ... ... lifetime: | Время жизни кэшированного индекса в секундах (0 = бесконечно) (Grav 1.7+) |
| ... object: | (Grav 1.7+) |
| ... ... enabled: | Установите true, чтобы включить кэширование Flex-объектов. Используется для кэширования данных объектов (Grav 1.7+) |
| ... ... lifetime: | Время жизни кэшированных объектов в секундах (0 = бесконечно) (Grav 1.7+) |
| ... render: | (Grav 1.7+) |
| ... ... enabled: | Установите true, чтобы включить кэширование рендеринга Flex. Используется для кэширования отрендеренного вывода (Grav 1.7+) |
| ... ... lifetime: | Время жизни кэшированного HTML в секундах (0 = бесконечно) (Grav 1.7+) |
Строгий режим¶
Строгий режим упрощает переход на будущие версии Grav: вы заранее переходите на более новые версии обработчиков YAML и Twig. Они могут быть несовместимы с некоторыми сторонними расширениями.
| Свойство | Описание |
|---|---|
| yaml_compat: | Включает обратную совместимость YAML |
| twig_compat: | Включает устаревший параметр autoescape в Twig |
| blueprint_compat: | Включает обратную совместимость строгой поддержки схем |
Внимание
Вам не нужно копировать весь файл конфигурации, чтобы переопределить его — можно переопределить как угодно мало или много. Просто убедитесь, что у вас точно такая же структура именования для конкретного параметра, который вы хотите переопределить.
Конфигурация сайта¶
Помимо файла system.yaml, Grav также предоставляет файл конфигурации по умолчанию site.yaml, который используется для некоторых настроек, специфичных для фронтенда: имени автора, электронной почты автора, а также некоторых ключевых параметров таксономии. Вы можете переопределить их так же, как и system.yaml, предоставив собственный файл конфигурации в user/config/site.yaml. Этот файл также можно использовать для произвольных параметров конфигурации, на которые вы хотите ссылаться из своего контента или шаблонов.
Файл system/config/site.yaml по умолчанию, поставляемый с Grav, выглядит примерно так:
Разберём элементы этого примера:
| Свойство | Описание |
|---|---|
| title: | title — это простая строковая переменная, к которой можно обращаться, когда нужно отобразить название сайта |
| author: | |
| ... name: | Имя автора сайта, к которому можно обращаться, когда это нужно |
| ... email: | Электронная почта по умолчанию для использования на сайте |
| taxonomies: | Произвольный список типов верхнего уровня, которые можно использовать для организации контента. Можно назначать контент конкретным типам таксономии, например категориям или тегам. Смело редактируйте или добавляйте свои |
| metadata: | Задать метаданные по умолчанию для всех страниц; см. раздел заголовки страниц для подробностей |
| summary: | |
| ... size: | Переменная для переопределения количества символов по умолчанию, используемого для задания размера аннотации при отображении части контента |
| routes: | Это простая карта, обеспечивающая возможности псевдонимов URL в Grav. Если вы перейдёте на /something/else, на самом деле вас отправят на /blog/sample-3. Смело редактируйте или добавляйте свои по мере необходимости. Regex-замены ((.*) - $1) теперь поддерживаются в конце псевдонимов маршрутов. Для оптимальной производительности их следует размещать в конце списка |
| (пользовательские параметры) | В этом файле можно создать любой параметр, какой захотите; хороший пример — параметр blog: route: '/blog', доступный в шаблонах Twig через site.blog.route |
Внимание
Для большинства людей самый важный элемент этого файла — список Taxonomy. Таксономии из этого списка должны быть определены здесь, если вы хотите использовать их в своём контенте.
Безопасность¶
Для повышения безопасности существует файл system/config/security.yaml, который задаёт некоторые разумные значения по умолчанию и используется плагином админки при сохранении контента, а также в новом разделе Отчёты в Инструментах.
Конфигурация по умолчанию выглядит так:
Если вы хотите внести изменения в эти параметры, скопируйте этот файл в user/config/security.yaml и редактируйте там.
Grav проверяет каждую часть имени загруженного файла, разделённую точками, на соответствие uploads_dangerous_extensions, а не только последнюю, поэтому photo.php.jpg будет отклонён. Расширения PHP (php, php2–php8, phar, phtml, pht, phtm и phps) отклоняются всегда, даже если вы удалите их из своей копии списка.
Другие параметры и файлы конфигурации¶
Пользовательская конфигурация полностью необязательна. Вы можете переопределить как угодно малую или большую часть параметров по умолчанию. Это относится и к системе, и к сайту, и к любой конфигурации плагинов на вашем сайте.
Вы также не ограничены файлами user/config/system.yaml или user/config/site.yaml, описанными выше. Вы можете создать любой произвольный файл конфигурации .yaml в папке user/config, какой захотите, и Grav автоматически его подхватит.
Например, если новый файл конфигурации называется user/config/data.yaml, а переменная YAML в этом файле называется count:
то к переменной можно обратиться в шаблоне Twig с помощью следующего синтаксиса:
Она также будет доступна из PHP из любого плагина с помощью кода:
Предупреждение
Вы также можете предоставить собственную схему, чтобы ваш файл можно было редактировать в админке. Ознакомьтесь с соответствующим рецептом для админки.
Пространства имён переменных конфигурации¶
Пути к файлам конфигурации будут использоваться как пространство имён для ваших параметров конфигурации.
Кроме того, можно поместить все параметры в один файл и использовать структуры YAML для указания иерархии параметров конфигурации. Это пространство имён строится из комбинации путь + имя файла + имя параметра.
Например, параметр author: Frank Smith в файле plugins/myplugin.yaml может быть доступен через plugins.myplugin.author. Однако у вас также может быть файл plugins.yaml, в котором есть параметр myplugin: author: Frank Smith, и он всё равно будет доступен по тому же пространству имён plugins.myplugin.author.
Некоторые примеры файлов конфигурации могут быть структурированы так:
| Файл | Описание |
|---|---|
| user/config/system.yaml | Глобальный файл системной конфигурации |
| user/config/site.yaml | Файл конфигурации, специфичный для сайта |
| user/config/plugins/myplugin.yaml | Отдельный файл конфигурации для плагина myplugin |
| user/config/themes/mytheme.yaml | Отдельный файл конфигурации для темы mytheme |
Внимание
Файл конфигурации с пространством имён переопределит или замаскирует все параметры с тем же путём в файлах конфигурации по умолчанию.
Конфигурация плагинов¶
Большинство плагинов поставляются с собственным файлом конфигурации YAML. Мы рекомендуем копировать этот файл в папку user/config/plugins/, а не редактировать параметры конфигурации прямо в файле, расположенном в папке плагина. Так обновление плагина не перезапишет ваши настройки, а все настраиваемые параметры будут в одном удобном месте.
Если у вас есть плагин user/plugins/myplugin с файлом конфигурации user/plugins/myplugin/myplugin.yaml, скопируйте этот файл в user/config/plugins/myplugin.yaml и редактируйте его там.
Файл YAML, находящийся в основной папке плагина, будет действовать как резервный. Любые параметры, указанные там, но отсутствующие в копии в папке пользователя, будут подхвачены и использованы Grav.
Конфигурация тем¶
К темам применяются те же правила, что и к плагинам. Если у вас есть тема user/themes/mytheme с файлом конфигурации user/themes/mytheme/mytheme.yaml, скопируйте этот файл в user/config/themes/mytheme.yaml и редактируйте его там.
Переменные окружения и файлы .env¶
Grav читает переменные окружения при запуске и использует их несколькими способами. Они полезны для значений, которые вы предпочли бы не коммитить в файлы конфигурации, например ключей API и паролей баз данных, а также для параметров, которые различаются на ваших серверах разработки, подготовки и производства.
Grav 2.0 может автоматически загружать эти переменные из файла .env в корне сайта. Это встроено в ядро, поэтому отдельный плагин DotEnv больше не нужен (и недоступен для Grav 2.0).
Файл .env¶
Создайте файл .env в корне вашей установки Grav рядом с index.php. Каждая строка задаёт одну переменную:
Каждая новая установка поставляется с шаблоном .env.example в корне. Скопируйте его в .env и раскомментируйте нужные записи в качестве отправной точки.
Внимание
ПРЕДУПРЕЖДЕНИЕ: файл .env обычно содержит секреты, поэтому его никогда не следует коммитить в систему контроля версий и делать доступным из веба. Стандартный .gitignore Grav уже исключает .env и файлы .env.local, а поставляемые конфигурации веб-сервера запрещают запросы к файлам .env. Если вы используете собственную конфигурацию сервера, убедитесь, что такие запросы блокируются.
Многоуровневые файлы .env¶
Для более сложных конфигураций можно разделить переменные между несколькими файлами. Они загружаются в порядке ниже, и каждый переопределяет значения, заданные предыдущими файлами:
| Файл | Назначение |
|---|---|
.env |
Базовые значения по умолчанию, безопасно делиться |
.env.local |
Переопределения для конкретной машины, не коммитятся |
.env.<environment> |
Значения для конкретного окружения, например .env.production |
.env.<environment>.local |
Переопределения для конкретной машины и окружения |
Суффикс <environment> берётся из переменной GRAV_ENVIRONMENT. Если она не задана, файлы для конкретного окружения пропускаются, и Grav возвращается к обычному определению окружения по имени хоста. Файл .env.local пропускается, когда GRAV_ENVIRONMENT равен test, чтобы тестовые запуски оставались предсказуемыми.
Примечание
Совет: переменные, уже заданные в реальном окружении сервера, всегда имеют приоритет над чем-либо в файле .env, поэтому .env никогда не перезаписывает учётные данные, предоставленные вашей хостинговой платформой.
Переопределение конфигурации¶
Установив для переменной GRAV_CONFIG истинное значение, вы можете переопределять любой параметр конфигурации через переменные окружения. Используйте префикс GRAV_CONFIG__, где двойное подчёркивание (__) обозначает вложенный уровень, который в YAML был бы точкой (.):
GRAV_CONFIG=true # Включить фичу переопределения
GRAV_CONFIG__system__cache__enabled=false # Устанавливает system.cache.enabled
GRAV_CONFIG__plugins__github__auth__token=xxxxxxxx
Примечание
Совет: переменные окружения всегда имеют текстовый тип, поэтому Grav преобразует слова true и false (в любом регистре) в настоящие значения да/нет. Всё остальное, включая числа, передаётся как текст. До Grav 2.0.23 преобразование вообще не выполнялось, и переопределение вроде =false приходило как непустая строка "false", которая читается как включено, а не выключено.
Чтобы длинные имена переменных оставались читаемыми, можно определять псевдонимы с префиксом GRAV_CONFIG_ALIAS__:
GRAV_CONFIG_ALIAS__GITHUB=plugins.github # Теперь GITHUB означает plugins.github
GRAV_CONFIG__GITHUB__auth__method=api # Устанавливает plugins.github.auth.method
GRAV_CONFIG__GITHUB__auth__token=xxxxxxxx # Устанавливает plugins.github.auth.token
Псевдонимы также позволяют обратиться к пути конфигурации, содержащему дефис. Имена переменных окружения допускают только буквы, цифры и подчёркивания, поэтому плагин, в слаге которого есть дефис, например translation-service, нельзя назвать напрямую. Поместите путь с дефисом в значение псевдонима, где дефисы разрешены, а затем ссылайтесь на псевдоним:
GRAV_CONFIG_ALIAS__TRANSLATIONSERVICE=plugins.translation-service
GRAV_CONFIG__TRANSLATIONSERVICE__anthropic__api_key=xxxxxxxx # Устанавливает plugins.translation-service.anthropic.api_key
Примечание
Совет: имя псевдонима сопоставляется как обычный текст внутри ключа, поэтому выбирайте отличительное имя из заглавных букв, которое случайно не встретится в другой части пути.
Переменные окружения и путей Grav¶
Несколько собственных переменных Grav читаются очень рано при запуске, поэтому их тоже можно задать в .env:
| Переменная | Назначение |
|---|---|
GRAV_ENVIRONMENT |
Выбирает активное окружение для конфигурации в user/env/ |
GRAV_ENVIRONMENT_PATH |
Путь к конкретной папке окружения |
GRAV_ENVIRONMENTS_PATH |
Базовый путь, содержащий все папки окружений |
GRAV_SETUP_PATH |
Расположение пользовательского файла setup.php |
GRAV_USER_PATH |
Расположение папки user |
Задание переменных на сервере¶
Файл .env — один из способов задать эти переменные. Их также можно задать напрямую в конфигурации сервера, которая имеет приоритет над файлом:
| Apache 2 | |
|---|---|
| NGINX php-fpm | |
|---|---|
Ваши собственные переменные (всё, что не является настройкой Grav) доступны плагинам и темам через PHP-функцию getenv():