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

Система конфигурации Drupal 8 обрабатывает конфигурацию унифицированно. По умолчанию Drupal хранит данные конфигурации в базе данных, но их можно экспортировать в файлы YAML, что позволяет управлять конфигурацией с помощью контроля версий. Однако существуют случаи, когда значения конфигурации необходимо переопределять для определенных целей. В Drupal 7 была переменная global $conf, которая обычно заполнялась в settings.php значениями условного переопределения для конфигурации. Большим недостатком этой системы было то, что переопределения перешли в фактическую конфигурацию. Когда форма конфигурации, которая содержала переопределенные значения, была сохранена, условное переопределение попало в хранилище фактической конфигурации.

Drupal 8 представляет систему переопределения конфигурации, которая:

• Поддерживает эти переопределения как временные слои поверх стандартных значений конфигурации
• Не использует переопределенные значения для форм конфигурации
• Может хранить переопределения с другими файлами конфигурации для поддержки подготовки и контроля версий (например, в случае переопределений языков; см. ниже).

Глобальная переменная $conf в Drupal 7 переименована в $config в Drupal 8 и активирована в системе конфигурации по умолчанию.

Глобальные переопределения

Drupal 8 сохраняет возможность использования global $config. Система конфигурации объединяет эти значения переопределения через реализацию Drupal\Core\Config\ConfigFactory::get(). Когда вы извлекаете значение из конфигурации, глобальная переменная $config получает шанс изменить возвращаемое значение:

// Get system site maintenance message text. This value may be overriden by
// default from global $config (as well as translations, see below).
$message = \Drupal::config('system.maintenance')->get('message');

Чтобы переопределить значения конфигурации в глобальном $config, например, в settings.php, обратитесь к их ключам конфигурации:

$config['system.maintenance']['message'] = 'Sorry, our site is down now.';

Для вложенных значений используйте ключи вложенного массива

$config['system.performance']['css']['preprocess'] = 0;

При использовании $config вне файла settings.php используйте предыдущий глобальный $config;

Может оказаться полезным определить доступные переменные конфигурации одним из следующих способов:

• просмотр их с помощью модуля «Configuration Manager» с использованием пользовательского интерфейса, который находится по адресу /admin/config/development/configuration/single/export
• проверять ваши файлы конфигурации сайтов YML напрямую,
• или запрашивая их с помощью drush.

drush config-list
drush config-get system.performance --include-overridden

Обратите внимание, что значения, переопределенные с помощью $config в settings.php, не будут доступны для просмотра из интерфейса администрирования Drupal (до # 2408549: в формах конфигурации не указывается, если исправлены переопределенные значения, до тех пор, пока вы не сможете использовать Configuration Override Warn или Config Override Inspector) или из проверки через drush (если вы не добавите флаг --include-overridden). Интерфейс администрирования отображает значения, сохраненные в конфигурации, так что вы можете вносить изменения в другие среды, которые не имеют переопределений.

Пример переопределения ключей API по соображениям безопасности см .: Переопределение ключей API платежей Commerce Gateway

Избегать переопределений

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

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

// Get the site name, with overrides.
$site_name = \Drupal::config('system.site')->get('name');

// Get the site name without overrides.
$site_name = \Drupal::config('system.site')->getOriginal('name', FALSE);
// Note that mutable config is always override free.
$site_name = \Drupal::configFactory()->getEditable('system.site')->get('name');

Вы также можете получить доступ к хранилищу настроек напрямую через сервис config.storage, который реализует StorageInterface::read(). Однако это редко правильный способ доступа к конфигурации.

Языковые переопределения

Например, для отправки электронной почты пользователю его конфигурация должна быть на языке пользователя, а не на странице. Запомните ранее используемый язык, установите правильный язык в зависимости от пользователя, выполните операции на основе конфигурации и установите язык обратно:

// Load the language_manager service
$language_manager = \Drupal::service('language_manager');

// Get the target language object
$langcode = $account->getPreferredLangcode();
$language = $language_manager->getLanguage($langcode);

// Remember original language before this operation.
$original_language = $language_manager->getConfigOverrideLanguage();
// Set the translation target language on the configuration factory.
$language_manager->setConfigOverrideLanguage($language);

$mail_config  = \Drupal::config('user.mail');

// Now send email based on $mail_config which is in the proper language.

// Set the configuration language back.
$language_manager->setConfigOverrideLanguage($original_language);

Система языковых переопределений также использует хранилище конфигурации для хранения переопределений (в отличие от глобальных переопределений на основе $config). Языковые переопределения хранятся в файлах, названных в честь их основного файла. Таким образом, если для указанного выше файла конфигурации user.mail существует переопределение для конкретного языка, он будет называться language.config.$langcode.user.mail. Файлы переопределения именуются с помощью language.config. префикс, затем код языка, а затем исходный ключ конфигурации. Хранение файлов с обычной конфигурацией обеспечивает поэтапный перевод конфигурации и может быть изменен, как и базовая конфигурация.

Как эти языковые файлы переопределения создаются в первую очередь? Локальный модуль интегрируется с системными событиями для создания файлов перевода для поставляемой конфигурации на основе информации схемы конфигурации. Существует также основной модуль перевода конфигурации, который обеспечивает общий пользовательский интерфейс для перевода конфигурации на основе схем. Он работает как с поставляемой, так и с пользовательской конфигурацией и работает с теми же файлами переопределения языка.

Предоставление переопределений из модулей

Также возможно обеспечить переопределение уровня модуля из любого модуля. Хотя ядро Drupal поддерживает глобальные переопределения, а также переопределения на основе языка, существуют варианты использования для многих других видов переопределений, включая основанные на ролях пользователей, контекстные, доменные, групповые и так далее. Модули могут определять свои собственные критерии для выполнения этих переопределений.

Когда ConfigFactory собирает предоставленные переопределения модуля, он вызывает любые службы, отмеченные как config.factory.override:

config_example.services.yml

services:
  config_example.overrider:
    class: Drupal\config_example\Config\ConfigExampleOverrides
    tags:
      - {name: config.factory.override, priority: 5}

Установите приоритет подписчика, чтобы указать приоритет переопределений. Переопределения с более высоким приоритетом будут иметь преимущество перед теми с более низким приоритетом (в случае того же имени конфигурации).

src/Config/ConfigExampleOverrides.php

namespace Drupal\config_example\Config;

use Drupal\Core\Cache\CacheableMetadata;
use Drupal\Core\Config\ConfigFactoryOverrideInterface;
use Drupal\Core\Config\StorageInterface;

/**
 * Example configuration override.
 */
class ConfigExampleOverrides implements ConfigFactoryOverrideInterface {

  /**
   * {@inheritdoc}
   */
  public function loadOverrides($names) {
    $overrides = array();
    if (in_array('system.site', $names)) {
      $overrides['system.site'] = ['name' => 'Overridden site name!'];
    }
    return $overrides;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheSuffix() {
    return 'ConfigExampleOverrider';
  }
  
  /**
   * {@inheritdoc}
   */
  public function getCacheableMetadata($name) {
    return new CacheableMetadata();
  }

  /**
   * {@inheritdoc}
   */
  public function createConfigObject($name, $collection = StorageInterface::DEFAULT_COLLECTION) {
    return NULL;
  }

}

Сами переопределения конфигурации работают на трех разных уровнях: language, modules и settings.php, причем последний из них имеет приоритет. Переопределения в файле settings.php имеют приоритет над значениями, предоставленными модулями. Переопределения, предоставляемые модулями, имеют приоритет над языком. Приоритет подписчика события для переопределений модуля устанавливает только приоритет по сравнению с переопределениями других модулей, его нельзя использовать для установки более высокого приоритета по отношению к переопределениям языка или settings.php.

Имейте в виду, что формы конфигурации в Drupal Core не используют переопределенные значения конфигурации. В приведенном выше примере переопределения модуля вы не увидите «Переопределенное имя сайта!» в /admin/config/system/site-information.

Стоит повторить, что если вам нужно прочитать исходные значения конфигурации в переопределении, например, для сравнения или слияния, вам нужно загрузить из \Drupal::configFactory, а не \Drupal::config, чтобы избежать вложенного цикла в вашу переопределение: 

$original = \Drupal::configFactory()->getEditable('system.site')->getOriginal('name', FALSE);

Еще больше справочной информации

Система переопределений в ее последней/текущей форме была добавлена ​​в # 2098119: Замените систему контекста config встроенной поддержкой локали и переопределениями на основе одного события.

Историческую / устаревшую информацию см. В # 1646580: Реализация событий и прослушивателей конфигурации и областей хранения для локализованной конфигурации, в которой изначально была представлена ​​система переопределения конфигурации, а также # 1763640: Ввести контекст конфигурации, чтобы сделать исходную конфигурацию и другие переопределения доступными там, где она была существенно модифицировано для работы с контекстным доступом. Специфичные для языка переопределения были добавлены позже в # 2020361: Создать LanguageConfigContext, чтобы активировать переопределения конфигурации на основе языка.