Перейти к содержанию

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

Все файлы конфигурации Grav написаны в синтаксисе YAML и имеют расширение .yaml. YAML очень интуитивен, поэтому его легко и читать, и писать, однако вы можете заглянуть на страницу YAML в главе «Для продвинутых», чтобы полностью понять доступный синтаксис.

Примечание

Совет: см. Безопасность > Конфигурация, чтобы быстро узнать, как защитить и оптимизировать вашу рабочую версию сайта.

Системная конфигурация

Grav старается максимально упростить всё для пользователя, и это касается конфигурации. Grav поставляется с разумными параметрами по умолчанию, которые содержатся в файле system/config/system.yaml.

Однако этот файл никогда не следует изменять. Вместо этого любые нужные изменения конфигурации должны храниться в файле user/config/system.yaml. Любой параметр в этом файле с той же структурой и именованием переопределит параметр, заданный в файле системной конфигурации по умолчанию.

Совет

В общем случае вам НИКОГДА не следует что-либо менять в папке system/. Всё, что делает пользователь (создание контента, установка плагинов, редактирование конфигурации и т. д.), должно выполняться в папке user/. Так проще обновляться, а все ваши изменения находятся в одном месте для резервного копирования, синхронизации и т. д.

Вот переменные, которые находятся в файле system/config/system.yaml по умолчанию:

Основные параметры

absolute_urls: false
timezone: ''
default_locale:
param_sep: ':'
wrapped_site: false
reverse_proxy_setup: false
force_ssl: false
force_lowercase_urls: true
custom_base_url: ''
username_regex: '^[a-z0-9_-]{3,16}$'
pwd_regex: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'
intl_enabled: true
http_x_forwarded:
  protocol: true
  host: false
  port: true
  ip: true

Эти параметры конфигурации не входят в собственные дочерние разделы. Это общие параметры, которые влияют на работу сайта, его часовой пояс и базовый 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+)

Языки

languages:
  supported: []
  default_lang:
  include_default_lang: true
  include_default_lang_file_extension: true
  pages_fallback_only: false
  translations: true
  translations_fallback: true
  session_store_active: false
  http_accept_language: false
  override_locale: false
  content_fallback: {}

Область Языки в файле задаёт языковые настройки сайта. Сюда входит, какие языки поддерживаются, указание языка по умолчанию в 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+)

Главная

1
2
3
home:
  alias: '/home'
  hide_in_urls: false

Раздел Главная — это место, где задаётся маршрут по умолчанию к домашней странице сайта. Также можно скрыть маршрут главной в URL.

Свойство Описание
alias: Путь по умолчанию для главной, например: /home или /
hide_in_urls: Скрыть маршрут главной в URL. Может быть true или false

Страницы

pages:
  type: regular
  theme: quark
  order:
    by: default
    dir: asc
  list:
    count: 20
  dateformat:
    default:
    short: 'jS M Y'
    long: 'F jS \a\t g:ia'
  publish_dates: true
  process:
    markdown: true
    twig: false
  twig_first: false
  never_cache_twig: false
  events:
    page: true
    twig: true
  markdown:
    extra: false
    auto_line_breaks: false
    auto_url_links: false
    escape_markup: false
    special_chars:
      '>': 'gt'
      '<': 'lt'
    valid_link_attributes:
      - rel
      - target
      - id
      - class
      - classes
  types: [html,htm,xml,txt,json,rss,atom]
  markdown_output:
    enabled: true
    frontmatter: true
    links: true
    max_links: 100
    absolute_urls: true
    token_header: true
  append_url_extension: ''
  expires: 604800
  cache_control:
  last_modified: false
  etag: false
  vary_accept_encoding: false
  redirect_default_route: false
  redirect_default_code: 302
  redirect_trailing_slash: true
  ignore_files: [.DS_Store]
  ignore_folders: [.git, .idea]
  ignore_hidden: true
  hide_empty_folders: false
  url_taxonomy_filters: true
  frontmatter:
    process_twig: false
    ignore_fields: ['form','forms']

Раздел Страницы файла 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']

Кэш

cache:
  enabled: true
  check:
    method: file
  driver: auto
  prefix: 'g'
  purge_at: '0 4 * * *'
  clear_at: '0 3 * * *'
  clear_job_type: 'standard'
  clear_images_by_default: false
  cli_compatibility: false
  lifetime: 604800
  gzip: false
  allow_webserver_gzip: false
  redis:
    socket: false
    password:
    database:

Раздел Кэш — это место, где можно настроить параметры кэширования сайта. Вы можете включить или отключить кэширование, выбрать метод и многое другое.

Свойство Описание
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

1
2
3
4
5
6
7
8
twig:
  cache: true
  debug: true
  auto_reload: true
  autoescape: false
  undefined_functions: true
  undefined_filters: true
  umask_fix: false

Раздел 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

Ресурсы

assets:
  css_pipeline: false
  css_pipeline_include_externals: true
  css_pipeline_before_excludes: true
  css_minify: true
  css_minify_windows: false
  css_rewrite: true
  js_pipeline: false
  js_pipeline_include_externals: true
  js_pipeline_before_excludes: true
  js_module_pipeline: false
  js_module_pipeline_include_externals: true
  js_module_pipeline_before_excludes: true
  js_minify: true
  enable_asset_timestamp: false
  enable_asset_sri: false
  collections:
    jquery: system://assets/jquery/jquery-2.x.min.js

Раздел Ресурсы позволяет настроить параметры, связанные с менеджером ресурсов (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. Подробнее об этом

Ошибки

1
2
3
errors:
  display: 0
  log: true

Раздел Ошибки определяет, как Grav отображает ошибки и ведёт их журнал.

Свойство Описание
display: Определяет, как отображаются ошибки. Введите 1 для полной трассировки, 0 для простой ошибки или -1 для системной ошибки
log: Записывать ошибки в папку /logs. Может быть true или false

Журнал

1
2
3
4
log:
  handler: file
  syslog:
    facility: local6

Раздел Журнал позволяет настроить альтернативные возможности ведения журнала для Grav.

Свойство Описание
handler: Обработчик журнала. Сейчас поддерживаются: file | syslog
syslog:
... facility: Категория (facility) для syslog

Отладчик

1
2
3
4
5
6
7
debugger:
  enabled: false
  provider: clockwork
  censored: false
  token: ''
  shutdown:
    close_connection: true

Раздел Отладчик даёт возможность активировать отладчик 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 для отладки

Изображения

images:
  default_image_quality: 85
  cache_all: false
  cache_perms: '0755'
  debug: false
  auto_fix_orientation: false
  seofriendly: false
  cls:
    auto_sizes: false
    aspect_ratio: false
    retina_scale: 1
  defaults:
    loading: auto

Раздел Изображения позволяет задать качество изображений по умолчанию, с которым они пересэмплируются, а также управлять кэшированием изображений и фичами отладки.

Свойство Описание
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+)

Медиафайлы

1
2
3
4
5
media:
  enable_media_timestamp: false
  unsupported_inline_types: []
  allowed_fallback_types: []
  auto_metadata_exif: false

Раздел Медиафайлы содержит параметры конфигурации, связанные с обработкой медиафайлов. Сюда входит отображение временных меток, размер загрузки и многое другое.

Свойство Описание
enable_media_timestamp: Включить временные метки медиафайлов
unsupported_inline_types: Массив поддерживаемых типов медиафайлов, которые нужно пытаться отображать встроенно. Эти типы файлов указываются в квадратных скобках []
allowed_fallback_types: Массив разрешённых типов медиафайлов, найденных при доступе через маршрут страницы. Эти типы файлов указываются в квадратных скобках []
auto_metadata_exif: Автоматически создавать файлы метаданных из данных Exif, где это возможно

Сессия

session:
  enabled: true
  initialize: true
  timeout: 1800
  name: grav-site
  uniqueness: path
  secure: false
  httponly: true
  samesite: Lax
  split: true
  domain:
  path:

Эти параметры определяют свойства сессии для вашего сайта.

Свойство Описание
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

1
2
3
4
5
6
gpm:
  releases: stable
  proxy_url:
  method: 'auto'
  verify_peer: true
  official_gpm_only: true

Параметры в разделе 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 для обеспечения безопасности; отключите это, чтобы разрешить другие источники

Учётные записи

1
2
3
accounts:
  type: regular
  storage: file

Параметры учётных записей позволяют попробовать новые экспериментальные Flex Users. По сути это означает, что пользователи хранятся как Flex-объекты, что даёт больше возможностей и производительности.

Свойство Описание
type: Тип учётной записи: regular или flex
storage: Тип хранилища Flex: file или folder

Flex

flex:
  cache:
    index:
      enabled: true
      lifetime: 60
    object:
      enabled: true
      lifetime: 600
    render:
      enabled: true
      lifetime: 600

Параметры кэша 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+)

Строгий режим

1
2
3
4
strict_mode:
  yaml_compat: true
  twig_compat: true
  blueprint_compat: false

Строгий режим упрощает переход на будущие версии 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: Grav                                 # Название сайта
default_lang: en                            # Язык сайта по умолчанию (потенциально используется темой)

author:
  name: John Appleseed                      # Имя автора по умолчанию
  email: 'john@example.com'                 # Электронная почта автора по умолчанию

taxonomies: [category,tag]                  # Произвольный список типов таксономии

metadata:
  description: 'My Grav Site'               # Описание сайта

summary:
  enabled: true                             # включить или отключить аннотацию страницы
  format: short                             # long = разделитель аннотации игнорируется; short = используется первое вхождение разделителя или размер
  size: 300                                 # Максимальная длина аннотации (символов)
  delimiter: ===                            # Разделитель аннотации

redirects:
#  '/redirect-test': '/'                    # Тест перенаправления ведёт на главную страницу
#  '/old/(.*)': '/new/$1'                   # Перенаправит /old/my-page на /new/my-page

routes:
#  '/something/else': '/blog/sample-3'      # Псевдоним для /blog/sample-3
#  '/new/(.*)': '/blog/$1'                  # Regex-преобразование любого URL /new/my-page в маршрут /blog/my-page

blog:
  route: '/blog'                            # Добавленное пользовательское значение (доступно через site.blog.route)

#menu:                                      # Пример меню
#    - text: Source
#      icon: github
#      url: https://github.com/getgrav/grav
#    - icon: twitter
#      url: http://twitter.com/getgrav

Разберём элементы этого примера:

Свойство Описание
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, который задаёт некоторые разумные значения по умолчанию и используется плагином админки при сохранении контента, а также в новом разделе Отчёты в Инструментах.

Конфигурация по умолчанию выглядит так:

xss_whitelist: [admin.super]
xss_enabled:
    on_events: true
    invalid_protocols: true
    moz_binding: true
    html_inline_styles: true
    dangerous_tags: true
xss_invalid_protocols:
    - javascript
    - livescript
    - vbscript
    - mocha
    - feed
    - data
xss_dangerous_tags:
    - applet
    - meta
    - xml
    - blink
    - link
    - style
    - script
    - embed
    - object
    - iframe
    - frame
    - frameset
    - ilayer
    - layer
    - bgsound
    - title
    - base
uploads_dangerous_extensions:
    - php
    - php2
    - php3
    - php4
    - php5
    - php7
    - php8
    - phar
    - phtml
    - pht
    - phtm
    - phps
    - html
    - htm
    - shtml
    - shtm
    - xhtml
    - xht
    - js
    - exe
    - md
    - yaml
    - yml
    - json
    - twig
    - ini
    - svgz
sanitize_svg: true

Если вы хотите внести изменения в эти параметры, скопируйте этот файл в 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:

count: 39

то к переменной можно обратиться в шаблоне Twig с помощью следующего синтаксиса:

{{ config.data.count }}

Она также будет доступна из PHP из любого плагина с помощью кода:

$count_var = Grav::instance()['config']->get('data.count');

Предупреждение

Вы также можете предоставить собственную схему, чтобы ваш файл можно было редактировать в админке. Ознакомьтесь с соответствующим рецептом для админки.

Пространства имён переменных конфигурации

Пути к файлам конфигурации будут использоваться как пространство имён для ваших параметров конфигурации.

Кроме того, можно поместить все параметры в один файл и использовать структуры 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. Каждая строка задаёт одну переменную:

GRAV_ENVIRONMENT=production
MY_API_KEY=super-secret-value

Каждая новая установка поставляется с шаблоном .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
1
2
3
4
5
6
<VirtualHost 127.0.0.1:80>
    ...

    SetEnv GRAV_ENVIRONMENT  production
    SetEnv MY_API_KEY        super-secret-value
</VirtualHost>
NGINX php-fpm
1
2
3
4
5
6
location ~ \.php$ {
    ...

    fastcgi_param GRAV_ENVIRONMENT  production;
    fastcgi_param MY_API_KEY        super-secret-value;
}

Ваши собственные переменные (всё, что не является настройкой Grav) доступны плагинам и темам через PHP-функцию getenv():

$key = getenv('MY_API_KEY') ?: null;