API простой конфигурации

На этой странице описывается API для получения и настройки данных конфигурации для простой конфигурации. (Это не для информации, хранящейся в объектах конфигурации.)

Данные конфигурации

Каждый модуль может предоставить конфигурацию по умолчанию. Например, настройки режима обслуживания определены в core/modules/system/config/install/system.maintenance.yml. В этом файле первая часть представляет собой пространство имен, представляющее, какой модуль предоставил эту конфигурацию (системный модуль в этом примере), за которой следует подсистема (обслуживание в этом примере). Файл должен находиться в каталоге config/install. Также он должен содержать символ «.» в имени файла для проверки в ConfigBase-> validateName($name). Этот файл содержит следующие YAML:

message: '@site is currently under maintenance. We should be back shortly. Thank you for your patience.'
langcode: en

Конфигурация также может быть вложенной, как в настройках производительности (system.performance.yml):

cache:
  page:
    enabled: '0'
    max_age: '0'
preprocess:
  css: '0'
  js: '0'
response:
  gzip: '0'

ВАЖНО: корневые ключи должны быть отображением

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

entity_type:
  commerce_order:
    foo: 'bar'
  node:
    foo: 'bar'
  user:
    foo: 'bar'

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

Взаимодействие с конфигурацией

Вы взаимодействуете с этими файлами через объект Config и создаете экземпляр объекта Config, вызывая функцию config() с именем файла за вычетом расширения. Вызов функции config вернет экземпляр \Drupal\Core\Config\ImmutableConfig.

// Immutable Config (Read Only).
$config = \Drupal::config('system.performance');

// Mutable Config (Read / Write).
$config = \Drupal::service('config.factory')->getEditable('system.performance');

Получив объект Config, вы можете взаимодействовать с ним различными способами.

Чтение конфигурации

Конфигурация читается с использованием метода get(). Это можно использовать несколькими способами. Чтобы прочитать фрагмент конфигурации, просто укажите его ключ.

$config = \Drupal::config('system.maintenance');
$message = $config->get('message');

Вызовы \Drupal::config() также могут быть связаны.

$message = \Drupal::config('system.maintenance')->get('message');

Чтобы прочитать вложенную конфигурацию, разделите ключи с помощью «.» персонаж.

$enabled = \Drupal::config('system.performance')->get('cache.page.enabled');

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

$page_cache = \Drupal::config('system.performance')->get('cache.page');

Это вернет массив с двумя ключами - «enabled» и «max_age».

Чтобы вернуть все данные в объекте конфигурации, просто вызовите get() без аргументов.

Также вы можете вернуть все конфигурационные ключи, доступные в системе, или только те ключи, которые начинаются с определенной подстроки (префикс $).

$keys = \Drupal::service('config.factory')->listAll($prefix = "");

Написание конфигурации

Чтобы изменить конфигурацию, вам нужно получить экземпляр \Drupal\Core\Config\Config (изменяемый объект конфигурации), вызвав getEditable() на фабрике конфигурации. Попытка внести изменение или вызов функции delete() / save() для экземпляра \Drupal\Core\Config\ImmutableConfig вызовет исключение ImmutableConfigException.

Это делается следующим образом:

\Drupal::service('config.factory')->getEditable('system.performance');

Конфигурация изменяется или добавляется с помощью метода set() и сохраняется с помощью метода save(). Обратите внимание, что конфигурация должна быть явно сохранена; простая установка данных в конфигурацию не сохраняет их.

Вы сохраняете данные в объект конфигурации так же, как вы их читаете, ссылаясь на ключи и сохраняя соответствующие данные. Синтаксис такой же, как variable_set(), который был в предыдущих версиях Drupal.

$config = \Drupal::service('config.factory')->getEditable('system.performance');

// Set a scalar value.
$config->set('cache.page.enabled', 1);

// Set an array of values.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Save your data to the database.
$config->save();

Функция set() также является цепочечной, поэтому, если вам нужно изменить только одно значение, вы можете сделать это в одной строке кода.

\Drupal::service('config.factory')->getEditable('system.performance')->set('cache.page.enabled', 1)->save();

Если вы хотите заменить все данные в объекте конфигурации, используйте функцию setData(). Вы не можете использовать setData(), чтобы заменить только подмножество данных - если вы хотите заменить что-либо меньше, чем весь объект, вы должны использовать вместо этого один или несколько вызовов set(). При использовании setData() вы должны указывать каждый ключ и значение в том же формате ассоциативного массива, который возвращается get() без аргументов. Для параметров производительности системы в system.performance.yml это будет выглядеть следующим образом:

// Set all values.
\Drupal::service('config.factory')->getEditable('system.performance')->setData([
    'cache' => [
      'page' => [
        'enabled' => '0',
        'max_age' => '0',
      ],
    ],
    'preprocess' => [
      'css' => '0',
      'js' => '0',
    ],
    'response' => [
      'gzip' => '0',
    ],
  ])
  ->save();

Удаление конфигурации

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

$config = \Drupal::service('config.factory')->getEditable('system.performance');
$config->clear('cache.page.max_age')->save();
$page_cache_data = $config->get('cache.page');

В этом примере $page_cache_data будет возвращать массив с одним ключом - «включен» - потому что «max_age» был не установлен.

Все наборы конфигурации могут быть удалены с помощью функции delete().

\Drupal::service('config.factory')->getEditable('system.performance')->delete();

Обратите внимание, что после этого не следует вызывать функцию save(), так как это создаст пустую версию набора конфигурации.

Лучшие практики

Избегайте создания экземпляров объектов конфигурации несколько раз в рамках одной и той же функции, поскольку это приводит к снижению производительности. Следующий код излишне создает экземпляр объекта конфигурации 'foo.bar' дважды.

\Drupal::service('config.factory')->getEditable('foo.bar')->set('foo', 'foo')->save();
\Drupal::service('config.factory')->getEditable('foo.bar')->set('bar', 'bar')->save();

Лучшим решением было бы создать экземпляр объекта конфигурации один раз, сохранить его в переменной и работать с этой переменной для остальной части вашей области кода.

$config = \Drupal::service('config.factory')->getEditable('foo.bar');
$config
  ->set('foo', 'foo')
  ->set('bar', 'bar')
  ->save();

Внедрение значений конфигурации в сервисы

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

services:
  app.service:
    class: Drupal/mail_module/Service
    factory: Drupal/mail_module/ServiceFactory:create
    arguments: ['@config.factory']

class ServiceFactory {
  static function create($config) {
    return new Service($config->get('mail.config')->get('transport'));
  }
}

class Service {
  public function __construct($transport) {
    $this->mailTransport = $transport;
  }
}

Пример был адаптирован из Как ввести значения конфигурации в сервисы?