Development

Documentation/ru_RU/book/1.0/05-Configuring-Symfony

You must first sign up to be able to contribute.

Version 14 (modified by postman, 10 years ago)
--

Глава 5 - Конфигурируем symfony

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

Эта глава объясняет, как работают конфигурационные файлы:

  • Настройки symfony хранятся в файлах написанных на YAML, хотя вы всегда можете выбрать другой формат.
  • Конфигурационные файлы могут находиться на уровне проекта, приложения, и модуля в файловой структуре проекта.
  • Вы можете задать несколько наборов настроек; в symfony, такой набор настроек называется режимом или средой (environment).
  • Заданные в конфигурационных файлах значения доступны из PHP кода вашего приложения.
  • В YAML файлах symfony можно пользоваться PHP и другими приемами. Это делает конфигурационную систему более гибкой.

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

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

Однако, такой подход имеет два серьезных недостатка:

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

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

  • Могущественной: Почти любой аспект, который может управляться через конфигурационные файлы, управляется через конфигурационные файлы.
  • Простой: Много деталей конфигурации не показываются в нормальном приложении, поскольку потребность корректировать их возникает редко.
  • Удобной: Разработчику легко читать, изменять, и создавать конфигурационные файлы.
  • Настраиваемой: Конфигурационный язык по умолчанию - YAML, но можно использовать INI, XML, или любой другой формат, который выберет разработчик.
  • Быстрой: Приложение не занимается конфигурационными файлами. Это делает конфигурационная система, она компилирует их в быстрообрабатываемые куски PHP кода.

Синтаксис YAML и cоглашения (сonventions) symfony

Для конфигурации symfony по умолчанию использует YAML файлы, вместо более традиционных форматов INI или XML. YAML файлы отображают структуру данных с помощью отступов, и их очень быстро писать. Достоинства YAML уже были описаны в главе 1. Тем не менее, при написании YAML файла, необходимо помнить о ряде соглашений. Эта секция познакомит вас с главными договоренностями. Полностью эта тема освещается на сайте YAML (http://www.yaml.org/).

Прежде всего, никогда не используйте табуляцию (tab); пользоваться нужно пробелами. Парсеры (parser) YAML не обрабатывают файлы с табуляций, поэтому отступы следует создавать пробелами (согласно договоренностям symfony, для отступа используется два пробела), как продемонстрировано в листинге 5-1.

Листинг 5-1 - В YAML файлах запрещена табуляция

# Никогда не используйте tab
all:
-> mail:
-> -> webmaster:  webmaster@example.com

# Используйте пробелы
all:
  mail:
    webmaster: webmaster@example.com

Если параметр это строка, которая начинается или заканчивается пробелом, заключите значение в одинарные кавычки. Если параметр — строка, содержащая специальные символы, ее также следует заключить в одинарные кавычки, как показано в листинге 5-2.

Листинг 5-2 - Нестандартные строки должны быть заключены в одинарные кавычки

error1: This field is compulsory
error2: '  This field is compulsory  '
error3: 'Don''t leave this field blank'   # Одинарные кавычки продублированы

Если значение параметра длинное, его можно задать в нескольких строках, также значением может быть мультистрока, состоящая из нескольких строчек (multiple-line string). В таких случаях используются дополнительные отступы и специальные метки (> и |). Пример приведен в листинге 5-3.

Листинг 5-3 - Определение длинной строки и мультистроки (multiple-line)

# Разбивая длинное значение, используйте метку >
# Каждая новая линия имеет дополнительный отступ
# Это делает YAML более читаемым
accomplishment: >
  Mark set a major league
  home run record in 1998.

# Для мультистрок используется метка |
# Все переносы строк сохранятся
# Дополнительных отступов в результирующей строке не будет
stats: |
  65 Home Runs
  0.278 Batting Average

Чтоб задать в качестве значения массив, нужно заключить элементы в квадратные скобки, или же использовать расширенный синтаксис с дефисом (dash), как показано в листинге 5-4.

Листинг 5-4 - YAML, Определение массива

# Короткий синтаксис для массивов
players: [ Mark McGwire, Sammy Sosa, Ken Griffey ]

# Расширенный синтаксис для массивов
players:
  - Mark McGwire
  - Sammy Sosa
  - Ken Griffey

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

Листинг 5-5 - YAML, определение ассоциативного массива

# Здесь есть ошибка, пропущены пробелы после двоеточий
mail: {webmaster:webmaster@example.com,contact:contact@example.com}

# Короткий синтаксис для ассоциативных массивов
mail: { webmaster: webmaster@example.com, contact: contact@example.com }

# Расширенный синтаксис для ассоциативных массивов
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com

Для булевых параметров используйте on, 1, или true, в случае позитивного значения, и off, 0, или false, в случае отрицательного. Листинг 5-6 содержит пример с булевыми параметрами.

Листинг 5-6 – YAML, булевые значения

true_values:   [ on, 1, true ]
false_values:  [ off, 0, false ]

Чтоб сделать YAML файл более читаемым не стесняйтесь добавлять комментарии (строки с пометкой #) и дополнительные пробелы, как например в листинге 5-7.

Листинг 5-7 - YAML, комментарии и выравнивание

# Это закомментированная строка
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com
  admin:     admin@example.com   # Дополнительные пробелы красиво выравнивают значения

В некоторых конфигурационных файлах symfony, вы иногда будете видеть строки, которые начинаются с символа # (и соответственно, игнорируемые парсером YAML), но которые выглядят как обычные настройки. Это одна из договоренностей (convention) symfony: настройки по умолчанию, наследуемые из других, находящихся в ядре symfony YAML файлов, продублированы в закомментированных строках в конфигурации вашего приложения. Если вы хотите изменить значение параметра, сначала нужно раскомментировать строку, как показано в листинге 5-8.

Листинг 5-8 - Настройки по умолчанию закомментированы

# По умолчанию кэш отключен
settings:
# cache: off

# Если вы хотите изменить эту настройку, следует сначала раскомментировать строку
settings:
  cache: on

Symfony иногда группирует параметры в категории. Все настройки данной категории прописаны с отступом после заголовка категории. Размещение длинных списков пар ключ: значение (key: value) в категориях улучшает читаемость конфигурационных файлов. Заголовки категорий начинаются с точки (.). Листинг 5-9 содержит пример категории.

Листинг 5-9 - Заголовок категории, похож на ключ, но начинается с точки

all:
  .general:
    tax:        19.6

  mail:
    webmaster:  webmaster@example.com

В этом примере, mail это ключ, а general — название категории. Взгляните на листинг 5-10. Все работает точно также, как будто категории не существует. Параметр tax прямой потомок (direct child) ключа all.

Листинг 5-10 - Заголовки категорий нужны для повышения читаемости, и при обработке игнорируются

all:
  tax:          19.6

  mail:
    webmaster:  webmaster@example.com

SIDEBAR Если вы не любите YAML

YAML это просто интерфейс для управления настройками, которые будут использованы в PHP коде. Соответственно конфигурация, заданная в YAML файлах, в итоге трансформируется в PHP. После просмотра приложения, можно проверить кэшированные настройки (например, в cache/myapp/dev/config/). Вы увидите PHP файлы, соответствующие вашей YAML конфигурации. Вы узнайте больше о настройках кэша (cache) позже в этой главе.

Хорошая новость — если вы не хотите использовать YAML файлы, можете выполнять работу системы конфигурации самостоятельно, как и прежде писать настройки на PHP или в другом формате (XML, INT, и т. д.). В этой книге, вы найдете альтернативные способы задать опции, и в главе 19 даже научитесь тому, как заменить обработчики конфигурации (configuration handler) symfony. Если использовать их разумно, эти приемы позволят обойти конфигурационные файлы или задать ваш собственный формат настроек.

Помогите, YAML файл убил мое приложение!

YAML файлы обрабатываются и превращаются в PHP хэши и массивы, потом эти параметры используются во многих частях приложения, чтоб изменить поведение view, controller, или model. Часто, если в YAML файле что-то не так, это не обнаруживается вплоть до того момента, когда понадобится использовать значение. Более того, ошибка или исключение (exception), которые выводятся, обычно неочевидным образом связано с YAML файлом.

Если ваше приложение неожиданно перестало работать после изменения настроек, нужно проверить, не сделали ли вы какую-то из распространенных ошибок:

  • Вы пропустили пробел между ключем (key) и значением (value):

    key1:value1      # Пропущен пробел после двоеточия
    
  • Ключи в последовательности имеют разный отступ:

    all:
      key1:  value1
       key2: value2  # Тут отступ не такой же как у других параметров
      key3:  value3
    
  • Наличие зарезервированного символа YAML в ключе или значении, не заключенном в кавычки:

    message: tell him: go way    # :, [, ], { и } в YAML зарезервированы
    message: 'tell him: go way'  # корректный синтаксис
    
  • Вы изменили закомментированную строку

    # key: value     # Это опция не обрабатывается, так как в начале строки стоит символ `#`
    
  • Вы повторно задали значение для одного ключа на одном уровне:

    key1: value1
    key2: value2
    key1: value3     # ключ key1 задан дважды, и будет равен последнему значению
    
  • Вы подразумевайте, что значение будет иметь какой либо специальный тип. На самом деле это всегда строка, и вам нужно ее конвертировать:

    income: 12,345   # пока вы не конвертируйте этот параметр, его тип значения — строка.
    

Обзор конфигурационных Файлов

Настройки рассортированы по файлам, согласно их природе. Файлы содержат параметры, или опции. Некоторые параметры могут быть переопределены на разных уровнях иерархии (проект, приложение, и модуль); некоторые существуют только на каком-то одном уровне. Следующие главы рассматривают конфигурационные файлы, которые связаны с их тематикой, и глава 19 рассказывает о продвинутой настройке (advanced configuration).

Конфигурация проекта

По умолчанию существует несколько конфигурационных файлов проекта. Вот список файлов, хранящихся в директории myproject/config/:

  • config.php: Этот файл обрабатывается первым при любом запросе или команде. Он содержит пути к файлам фреймворка, вы можете менять их, чтоб использовать нестандартную установку. Если вы зададите какие-то константы в конце файла, то они будут доступны из любого приложения проекта. Обратитесь к главе 19, чтоб узнать о продвинутом использовании этого файла.
  • databases.yml: Тут вы определяете установки соединения и доступа к базе данных (хост, логин, пароль, имя базы, и т. д.). Глава 8 расскажет больше об этом. Эти настройки могут быть переопределены на уровне приложения. Глава 16 описывает для каких возможностей symfony используется этот файл.
  • properties.ini: Файл содержит несколько параметров, используемых CLI symfony, включая имя проекта и опции подключения для удаленных серверов. Глава 16 содержит обзор возможностей (feature), которые используют этот файл.
  • rsync_exclude.txt: Этот файл определяет директории, которые должны игнорироваться при синхронизации между серверами. Подробнее об этом в главе 16.
  • schema.yml и propel.ini: Тут хранятся настройки, необходимые Propel (ORM symfony) для доступа к данным. Они используются для работы библиотек Propel с библиотеками symfony и данными вашего проекта. schema.yml содержит представление реляционной модели данных проекта. propel.ini генерируется автоматически, поэтому скорей всего вам не понадобится изменять его. Если вы не используйте Propel, эти файлы вам не понадобятся. Глава 8 описывает их подробнее.

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

Конфигурация приложения

Главная часть настроек это настройки приложения. Основные константы определены в фронт-контроллере (он находится в директории web/), опции для файлов интернационализации содержатся в YAML файлах директории i18n/, остальные настройки — в директории config/. Также дополнительные, скрытые, но полезные для приложения настройки, заданы в файлах фреймворка.

Настройки фронт-контроллера

Самые главные настройки приложения находятся в фронт-контроллере; это первый скрипт, который выполняется при запросе (request). Взгляните на стандартный web/index.php, приведенный в листинге 5-11.

Листинг 5-11 - Стандартный фронт-контроллер для рабочей среды (production front controller)

[php]
<?php

define('SF_ROOT_DIR',    dirname(__FILE__).'/..');
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       true);

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

sfContext::getInstance()->getController()->dispatch();

После задания имени приложения (myapp) и среды (prod), но до передачи обработки запроса дальше, вызывается основной конфигурационный файл, в котором заданы несколько полезных констант:

  • SF_ROOT_DIR: Корневая директория проекта (Этот параметр обычно должен равняться значению по умолчанию, если вы не хотите менять файловую структуру).
  • SF_APP: Имя приложения в проекте. Необходимо для составления путей.
  • SF_ENVIRONMENT: Название среды (environment). Может быть prod, dev, или любым другим, заданным вами. Этот параметр определяет, какой набор настроек нужно использовать. Режимы (environment) будут подробно рассмотрены позже в этой главе.
  • SF_DEBUG: Опция активирующая режим отладки (debug mode). Подробнее в главе 16.

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

SIDEBAR Корневая директория может быть где угодно.

Только файлы и скрипты из веб директории (в symfony это папка web/) доступны извне. Там находятся скрипты фронт-контроллеров, изображения, таблицы стилей, и яваскрипты. Все остальные файлы не должны находиться в веб директории — это значит, что они могут находиться в любом другом месте.

Фронт-контроллер обращается к ненаходящимся в свободном доступе файлам через путь SF_ROOT_DIR. Традиционно, корневая директория находится уровнем выше от директории web/. Но вы можете выбрать совершенно другую структуру. Представим, что файловая структура состоит из двух директорий, одна с открытым доступом и другая с закрытым:

symfony/    # Закрытый доступ
  apps/
  batch/
  cache/
  ...
www/        # Открытый доступ
  images/
  css/
  js/
  index.php

В этом случае symfony/ — корневая директория. Поэтому в фронт-контроллере index.php параметр SF_ROOT_DIR задан следующим образом:

define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony');

Глава 19 даст вам больше информации о том, как настроить symfony для работы с нестандартной файловой структурой.

Основные настройки приложения

Основные настройки приложения находятся в файлах директории myproject/apps/myapp/config/:

  • app.yml: Этот файл содержит настройки специфические для данного приложения; это глобальные переменные, используемые в бизнес логике и логике приложения, которые нет нужды хранить в базе данных. В этом файле часто хранятся налоговые ставки, цены на доставку, e-mail адреса. По умолчанию он пустой.
  • config.php: Этот файл отвечает за начальную загрузку приложения, это означает, что в нем происходят все основные инициализации необходимые для начала работы приложения. Тут вы можете изменять файловую структуру, или добавить специфические для данного приложения константы (Глава 19 предоставляет об этом более подробную информацию). В начале файла подключается (include) config.php проекта.
  • factories.yml: Symfony предоставляет свои собственные классы для обработки view, запроса (request), ответа (response), сессии (session), и т. д. Если вы желаете использовать свои собственные классы, то нужно определить их в этом файле. Глава 19 рассматривает эту возможность подробнее.
  • filters.yml: Фильтры это куски кода, выполняемые при каждом запросе (request). В этом файле можно задать какие фильтры необходимо использовать. Эти настройки могут быть перезаданы на уровне модуля. Глава 6 детально рассматривает фильтры.
  • logging.yml: В этом файле можно задать уровень детализации для журналов событий (log), чтоб облегчить управление приложением и отладку. Использование этой возможности рассмотрено в главе 16.
  • routing.yml: Здесь хранятся правила роутинга, благодаря которым обеспечивается трансформация нечитаемых и неудобных для добавления в закладки (unbookmarkable) URL в говорящие сами за себя ЧПУ(человеко-понятные-урл) адреса. В новом приложении по умолчанию существует несколько правил. Глава 9 целиком посвящена ссылкам и роутингу.
  • settings.yml: Основные настройки приложения symfony содержатся в этом файле. Тут вы можете задать многоязычно приложение или нет, язык используемый по умолчанию, время ожидания запроса (request timeout), включен ли кэш. Изменением одной строки вы можете прекратить работу приложения, чтоб заняться технической поддержкой или обновить (upgrade) какой-то компонент. Частоупотребляемые опции и их использование описано в главе 19.
  • view.yml: Структура view по умолчанию (имя главного шаблона (layout), заголовок (title), теги meta; стандартные таблицы стилей и подключаемые яваскрипты; тип контента по умолчанию, и т. д.) задаются в этом файле. Тут также определяются значения по умолчанию для тегов title и meta. Глава 7 расскажет больше об этом файле. Эти установки могут быть перезаданы для каждого модуля.

Настройки интернационализации

Интернационализа́ция (англ. internationalization) — процесс адаптации продукта, такого как программное или аппаратное обеспечение, к языковым и культурным особенностям региона (регионов), отличного от того, в котором разрабатывался продукт. В английском языке для слова «internationalization» принято сокращение «i18n». При этом число 18 означает количество пропущенных между «i» и «n» букв.

wikipedia.org

Многоязычные приложения могут показывать странички на нескольких языках. Это требует специальных настроек. Такие опции содержатся в двух местах:

  • i18n.yml в директории приложения config/ : Этот файл задает основные опции перевода, такие как, используемая по умолчанию для перевода культура (default culture), хранятся переводы в базе данных или в файлах, формат переводов.
  • Файлы переводов в директории приложения i18n/: Это в основном словари, которые предоставляют перевод для каждой фразы, используемой в шаблонах приложения. С помощью них на страничке выводится переведенный текст при переключении языка.

Отметим, что активируются возможности i18n в файле settings.yml. Вы найдете больше информации по этой теме в главе 13.

Дополнительные настройки приложения

Еще один набор конфигурационных файлов находится в установочной директории symfony ($sf_symfony_data_dir/config/). Находящейся в них опции либо определены по умолчанию, и потребность изменять их возникает редко, либо общие для всех проектов. Однако, если вы пожелайте изменить эти настройки, просто создайте пустой файл с таким же именем в вашей директории myproject/apps/myapp/config/ и перезадайте в нем нужные опции. Заданные на уровне приложения настройки имеют больший приоритет, чем настройки определенные в фреймворке. Вот список конфигурационных файлов директории config/ фреймворка:

  • autoload.yml: Файл содержит опции автоподключения. Эта возможность позволит не подключать пользовательские классы в вашем коде, если они находятся в специальных директориях. Детальней — в главе 19.
  • constants.php: Этот файл задает файловую структуру приложения по умолчанию. Чтоб перезадать ее, используйте config.php приложения, как объясняется в главе 19.
  • core_compile.yml и bootstrap_compile.yml: Это списки классов, которые нужно подключить для запуска приложения (bootstrap_compile.yml) и для обработки запроса (core_compile.yml). В действительности, эти файлы объединены в один оптимизированный PHP файл без комментариев, который ускоряет работу, минимизируя количество операций доступа к файлу (для обработки одного запроса загружается один файл вместо более чем 40). Это в особенности удобно, если вы не используйте PHP акселератор. Методы оптимизации описываются в главе 18.

PHP акселератор это расширение (extension) призванное увеличить быстродействие приложений написанных на PHP. Основная идея PHP акселератора — бинарный код PHP скриптов кэшируется и используется в дальнейшей работе приложения.

переводчик

  • config_handlers.yml: Тут вы можете поменять обработчик (handler) для каждого конфигурационного файла. Глава 19 описывает эту возможность подробнее
  • php.yml: Этот файл проверяет правильно ли заданы переменные php.ini и также позволяет перезадать их, если это необходимо. Обратитесь к главе 19 за деталями.

Настройки модуля

По умолчанию модуль не имеет собственных настроек. Но, если возникнет необходимость, вы можете перезадать некоторые опции приложения для данного модуля. К примеру, можно переопределить параметры используемые в HTML только для всех действий (action) данного модуля, или подключить какой-то специфический яваскрипт. Вы также можете задать новые параметры, доступные только в данном модуле, таким образом обеспечив инкапсуляцию.

Как вы уже наверное догадались, настройки модуля содержатся в директории myproject/apps/myapp/modules/mymodule/config/. Вот список файлов:

  • generator.yml: Этот файл нужен для сгенерированных на основе таблицы базы данных модулей (scaffoldings и админинтерфесы; scaffolding — (англ.) строительные леса). Тут определяется, как будут отображаться строки и поля, какие действия будут доступны пользователю (фильтры, сортировка, кнопки, и т. д.). Глава 14 расскажет больше.
  • module.yml: Тут содержатся пользовательские параметры индивидуальные для данного модуля (эквивалент app.yml, но на уровне модуля) и некоторые настройки действия (action). В главе 6 предоставлено больше информации.
  • security.yml: Файл определяет ограничения доступа. Тут можно разрешить доступ к модулю только для зарегистрированных пользователей или для какой-то подгруппы зарегистрированных пользователей, имеющих специальные права. Глава 6 рассматривает эту тему подробно.
  • view.yml: Настройки view хранятся здесь. Они могут быть заданы как для всех действий (action), так и индивидуально для каждого. Как обычно, эти опции имеют больший приоритет, чем опции заданные во view.yml приложения. Обратитесь к главе 7 за деталями.
  • Файлы валидации данных: Несмотря на то, что они находятся в директории validate/, а не в config/, это тоже часть конфигурации модуля. Эти файлы используются для контроля над вводимыми через формы данными. Вы узнаете больше об их использовании в главе 10.

Большинство конфигурационных файлов модуля предоставляют возможность определить параметры для всех действий (action) и view модуля, или для какого-то их подмножества.

SIDEBAR Слишком много файлов?

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

В большинстве случаев вам не понадобится менять настройки, поскольку опции по умолчанию соответствуют наиболее распространенным требованиям. Каждый файл соответствует какой-то конкретной возможности, и в последующих главах они будут последовательно и подробно описаны. Когда вы будете рассматривать один файл, вы четко увидите что он делает и как он организован. Для профессиональной веб разработки, настройки по умолчанию могут оказаться не совсем подходящими. Конфигурационные файлы позволяют легко изменять поведение механизмов symfony. Представьте сколько PHP кода необходимо чтоб достичь аналогичных возможностей контроля. Если все настройки были бы собраны в одном файле, файл не только был бы совершенно не читаемым, но и переопределить настройки на нескольких уровнях иерархии (проект/приложение/модуль) было бы невозможным (см. секцию «Каскад настроек» ниже в этой главе)

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

Режимы (environments)

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

Что такое режим (environment)?

Приложение может быть запущено в различных режимах (environment). Различные режимы используют один и тот же PHP код (за исключением фронт-контроллеров), но могут иметь совершенно разную конфигурацию. Для каждого приложения symfony по умолчанию предоставляет три режима (environment): рабочий режим (prod), тестовый режим (test), и режим разработки (dev). Вы можете добавить свои, пользовательские режимы.

Приведу здесь переводы терминов:

Environment — среда, режим
Production environment (prod) — рабочая среда, рабочий режим, режим prod
Development environment (dev)— среда разработки, режим разработки, режим dev
Test environment (test)— среда тестирования, режим тестирования, режим test

переводчик

По существу режим (environment) и конфигурация это синонимы. Например, в тестовом режиме в журнал событий заносится предупреждения (alert) и ошибки (error), а в рабочем режиме только ошибки. Зачастую в режиме разработки кэш не активирован, но в рабочем режиме и режиме тестирования кэш работает. Для режимов dev и test могут понадобиться тестовые данные, которые хранятся в базе отдельно от реальных данных, используемых в рабочем (prod) режиме. Поэтому и настройки базы данных для разных режимов будут разные. Все режимы (environment) могут находиться на одной машине, хотя на реальном сервере (production server) обычно содержится только рабочий режим (prod).

В режиме разработчика, все опции для журналов событий (log) и отладки включены, видь отладка важнее чем быстродействие. И наоборот, в рабочем режиме все настройки по умолчанию заточены под быстродействие, то есть в режиме prod многие возможности отключены. Хорошее правило, при работе над какой-то новой возможностью проекта, наблюдать за тем что получается в режиме dev, и когда вы наконец-то будете удовлетворены результатом, переключится в рабочий режим (prod) и проверить быстродействие.

Режим тестирования отличается от режимов dev и prod другим. Вы можете действовать в этом режиме только через командную строку с целью функционального тестирования или запуска командных (batch) скриптов. Режим тестирования близок к рабочему режиму, но не доступен через браузер. Он эмулирует использование cookies и других компонентов HTTP.

Чтоб сменить режим в котором вы просматривайте приложение, просто используйте другой фронт-контроллер. До сих пор, вы видели все только в режиме разработки, поскольку все URL используемые в примерах вызывали фронт-контроллер соответствующий режиму dev:

http://localhost/myapp_dev.php/mymodule/index

Если вы хотите посмотреть приложение в рабочем режиме, вызовите соответственный фронт-контроллер:

http://localhost/index.php/mymodule/index

Если на сервере включен mod_rewrite, вы можете использовать правила преобразования (rewriting rule), заданные в web/.htaccess. Они задают фронт-контроллер рабочего режима как скрипт исполняемый по умолчанию, и благодаря этому можно использовать адреса наподобие:

http://localhost/mymodule/index

SIDEBAR Режим и сервер

Не путайте понятия режима и сервера. В symfony, разные режимы это разные наборы настроек, и им соответствуют разные фронт-контроллеры (скрипт выполняющий запрос). Разным серверам соответствуют разные доменные имена в URL.

http://localhost/myapp_dev.php/mymodule/index
       _________ _____________
        сервер        режим

Обычно, разработчики работают над приложением на своем сервере (development server), предназначенном для разработки и отключенном от Интернета. На нем можно изменять настройки сервера и PHP. Когда приходит время выпуска проекта, файлы приложения переносятся на реальный сервер (production server) и их делают доступными для пользователей.

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

Не нужно создавать директорию или использовать CLI symfony, чтоб добавить новый режим. Просто создайте новый фронт-контроллер и измените в нем название режима (environment). Этот режим унаследует все настройки по умолчанию плюс опции общие для всех режимов. Следующая глава покажет как это делать.

Каскад настроек

Одну и ту же настройку можно задать в нескольких местах. К примеру, вы можете установить mime-type всех ваших страниц в text/html - за исключением страниц модуля rss, которому требуется mime-type text/xml. В symfony вы можете задать первый тип в файле myapp/config/view.yml и второй в myapp/modules/rss/config/view.yml. Система конфигурации знает, что опция, заданная на уровне модуля, имеет больший приоритет, чем опция, заданная на уровне приложения.

Multipurpose Internet Mail Extensions (MIME) (Многоцелевые Расширения Почты Интернет) — стандарт, описывающий передачу различных типов данных по электронной почте, либо спецификация для форматирования не-текстовых (не-ASCII) сообщений, чтобы их можно было пересылать по Internet. MIME является также фундаментальным компонентом коммуникационных протоколов, таких как HTTP, которым нужно, чтобы данные передавались в контексте сообщений подобных e-mail, даже если данные реально не являются e-mail.

wikipedia.org

Фактически, в symfony есть несколько уровней конфигурации:

  • Уровни в глубину
    • Стандартные настройки находящийся в фреймворке
    • Глобальная конфигурация всего проекта (в myproject/config/)
    • Конфигурация приложения проекта (в myproject/apps/myapp/config/)
    • Локальная конфигурация модуля (в myproject/apps/myapp/modules/mymodule/config/)
  • Уровни режимов:
    • Индивидуальные настройки для режима
    • Настройки общие для всех режимов

Большая часть опций могут быть разными для разных режимов. Многие конфигурационные YAML файлы поделены на несколько секций. Каждая секция соответствует какому-то режиму, и еще в одной секции содержатся настройки общие для всех режимов. Типичный конфигурационный файл symfony выглядит как показано в листинге 5-12.

Листинг 5-12 - Структура конфигурационных файлов symfony

# Опции рабочего режима (production environment)
prod:
  ...

# Опции режима разработки (development environment)
dev:
  ...

# Опции режима тестирования (test environment)
test:
  ...

# Опции заданного пользователем режима (custom environment)
myenv:
  ...

# Опции общие для всех режимов
all:
  ...

Так же, фреймворк задает стандартные значения настроек, они находятся не в файловой структуре проекта, а в директории фреймворка $sf_symfony_data_dir/config/. Эти опции наследуются всеми приложениями. Пример стандартной конфигурации приведен в листинге 5-13.

Листинг 5-13 - Стандартные настройки используемые по умолчанию в файле $sf_symfony_data_dir/config/settings.yml

 # Стандартные настройки:
 default:
   default_module:         default
   default_action:         index
   ...

Эти опции продублированы в настройках проекта, приложения и модуля. Но там они закомментированы, как показано в листинге 5-14. Таким образом понятно, что эти параметры заданы по умолчанию, но могут быть изменены.

Листинг 5-14 - Стандартные настройки продублированы в файле myapp/config/settings.yml

#all:
 #  default_module:         default
 #  default_action:         index
 ...

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

  1. Модуль (module)
  2. Приложение (application)
  3. Проект (project)
  4. Конкретный режим (specific environment)
  5. Все режимы (all environments)
  6. Стандартная конфигурация (default)

Настройки кэша (cache)

Обработка YAML файлов и каскадов настроек может серьезно замедлить обработку каждого запроса. Для того чтоб ускорить работу приложения symfony предлагает встроенный механизм кэширования.

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

Например, если файл app.yml содержит это:

all:                   # Опции общие для всех режимов
  mail:
    webmaster:         webmaster@example.com

то файл config_app.yml.php, находящийся в директории cache/ вашего проекта, будет содержать это:

[php]
<?php

sfConfig::add(array(
  'app_mail_webmaster' => 'webmaster@example.com',
));

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

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

Из всего этого следует один важный вывод. Если вы изменили настройки в рабочем режиме (prod), то для того чтобы изменения вступили в силу необходимо заново обработать конфигурационные файлы. Для этого нужно просто очистить кэш удалив все содержимое папки cache/ или, еще проще, вызвав команду symfony clear-cache:

> symfony clear-cache

Доступ к конфигурации из кода

Все конфигурационные файлы трансформированы в PHP, и многие настройки автоматически используются фреймворком без дальнейшего вмешательства. Однако, иногда вам может понадобиться получить значение опции из кода (в действии (action), шаблоне, пользовательском классе, и т. д.). Настройки заданные в файлах settings.yml, app.yml, module.yml, logging.yml, и i18n.yml доступны через специальный класс sfConfig.

Класс sfConfig

Вы можете получать значения опций через класс sfConfig. Это реестр конфигурационных параметров. Через методы типа getter, опции доступны из любой точки кода:

[php]
// Получение опции
parameter = sfConfig::get('param_name', $default_value);

Вы также можете задать или перезадать, опцию через PHP код:

[php]
// Задание опции
sfConfig::set('param_name', $value);

Имя параметра строится из нескольких частей, разделенных подчеркиванием и идущих в таком порядке:

  • Префикс, связанный с именем конфигурационного файла (sf_ для settings.yml, app_ для app.yml, mod_ для module.yml, sf_i18n_ для i18n.yml, и sf_logging_ для logging.yml)
  • Родительские ключи (если есть) в нижнем регистре
  • Имя ключа в нижнем регистре

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

К примеру, листинг 5-16 показывает, как получить опции заданные в файле app.yml, приведенном в листинге 5-15.

Листинг 5-15 - Пример конфигурационного файла app.yml

all:
  version:        1.5
  .general:
    tax:          19.6
  default_user:
    name:         John Doe
  mail:
    webmaster:    webmaster@example.com
    contact:      contact@example.com
dev:
  mail:
    webmaster:    dummy@example.com
    contact:      dummy@example.com

Листинг 5-16 - Получение опций из PHP кода в режиме разработки (dev)

[php]
echo sfConfig::get('app_version');
 => '1.5'
echo sfConfig::get('app_tax');   // Помните, что заголовки категорий игнорируются
 => '19.6'
echo sfConfig::get('app_default_user_name');
 => 'John Doe'
echo sfConfig::get('app_mail_webmaster');
 => 'dummy@example.com'
echo sfConfig::get('app_mail_contact');
 => 'dummy@example.com'

Таким образом, все преимущества PHP констант присущи конфигурации symfony, но недостаток, связанный с тем что константу можно изменить — устранен.

Файл settings.yml, где вы задаете настройки для приложения, эквивалентен ряду вызовов метода sfConfig::set(). Листинг 5-18 показывает как обрабатывается листинг 5-17.

Листинг 5-17 - Выдержка из файла settings.yml

all:
  .settings:
    available:              on
    path_info_array:        SERVER
    path_info_key:          PATH_INFO
    url_format:             PATH

Листинг 5-18 - Вот что делает symfony, обрабатывая settings.yml.

[php]
sfConfig::add(array(
  'sf_available' => true,
  'sf_path_info_array' => 'SERVER',
  'sf_path_info_key' => 'PATH_INFO',
  'sf_url_format' => 'PATH',
));

Разъяснения по поводу опций из файла settings.yml содержатся в главе 19.

Пользовательские опции приложения и файл app.yml

Большинство опций связанных с возможностями вашего приложения должны храниться в файле app.yml, который находится в директории myproject/apps/myapp/config/. Этот файл зависит от используемого режима (environment-dependent) и по умолчанию пустой. Заносите сюда любую нужную опцию, и используйте класс sfConfig для доступа к параметру из кода. В листинге 5-19 содержится пример.

Листинг 5-19 - Пример app.yml, в котором задаются операторы кредитными карточками, приемлемые для данного сайта

all:
  creditcards:
    fake:             off
    visa:             on
    americanexpress:  on

dev:
  creditcards:
    fake:             on

Чтоб узнать принимают ли кредитные карточки fake в данном режиме (environment), получите соответствующие значение:

[php]
sfConfig::get('app_creditcards_fake');

TIP Прежде чем задать константу или опцию в одном из ваших скриптов подумайте, не лучше ли поместить ее в файл app.yml. Это очень удобное место для хранения всех опций приложения.

Если созданные вами параметры очень сложно задать чeрез синтаксис app.yml, можно создать ваш собственный синтаксис. В этом случае, можно хранить настройки в новом файле и обрабатывать его новым обработчиком конфигурации. Обратитесь к главе 19 за более подробной информацией об обработчиках.

Советы как получить больше пользы от конфигурационных файлов

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

Использование констант в конфигурационных файлах

Некоторые опции зависят от значений других опций. Чтоб избежать повторного задания параметра, symfony поддерживает константы в YAML файлах. При обнаружении имени опции (значение которой можно получить через sfConfig::get()), написанном в верхнем регистре и заключенном между символами %, обработчики настроек заменяют их на текущее значение. Посмотрите на пример в листинге 5-20.

Листинг 5-20 - Использование констант в YAML файлах, пример из autoload.yml

autoload:
  symfony:
    name:           symfony
    path:           %SF_SYMFONY_LIB_DIR%
    recursive:      on
    exclude:        [vendor]

Параметру path будет присвоено значение возвращенное sfConfig::get(‘sf_symfony_lib_dir’). Если вы хотите чтоб один конфигурационный файл зависел от другого, убедитесь, что второй файл уже обработан (взгляните на исходники symfony, чтоб узнать в каком порядке обрабатываются файлы). app.yml обрабатывается последним, поэтому в нем можно использовать все опции из других конфигурационных файлов.

Использование скриптов в настройках

Ваши настройки могут зависеть от каких либо внешних параметров (как база данных или другой конфигурационный файл). Для работы с такими случаями, конфигурационные файлы сначала обрабатывает PHP и только потом YAML парсер (parser). Это значит, что вы можете поместить PHP код в YAML файл, как сделано в листинге 5-21.

Листинг 5-21 - YAML файл может включать в себя PHP

all:
  translation:
    format:  <?php echo sfConfig::get('sf_i18n') == true ? 'xliff' : 'none' ?>

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

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

Считывание YAML файла напрямую

Для того чтобы прочитать YAML файл напрямую вы можете использовать класс sfYaml. Это YAML парсер (parser), который может превратить YAML файл в ассоциативный PHP массив. Листинг 5-22 демонстрирует пример YAML файла, и листинг 5-23 показывает как его обработать.

Листинг 5-22 - Файла test.yml

house:
  family:
    name:     Doe
    parents:  [John, Jane]
    children: [Paul, Mark, Simone]
  address:
    number:   34
    street:   Main Street
    city:     Nowheretown
    zipcode:  12345

Листинг 5-23 - Использование класса sfYaml для получения ассоциативного массива

[php]
$test = sfYaml::load('/path/to/test.yml');
print_r($test);

Array(
  [house] => Array(
    [family] => Array(
      [name] => Doe
      [parents] => Array(
        [0] => John
        [1] => Jane
      )
      [children] => Array(
        [0] => Paul
        [1] => Mark
        [2] => Simone
      )
    )
    [address] => Array(
      [number] => 34
      [street] => Main Street
      [city] => Nowheretown
      [zipcode] => 12345
    )
  )
)

Итого

Для простоты и читаемости конфигурационной системы symfony используется язык YAML. Возможность работать в нескольких режимах и каскадная система опций (definition cascade) обеспечивает разработчику гибкость. Благодаря объекту sfConfig некоторые настройки доступны из кода, особенно параметры из файла app.yml

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

Перевел Алексей Гоголев postman [at] dev [dot] co [dot] ua

Статья также доступна по адресу http://developer.co.ua/posts/view/glava_5_konfiguriruem_symfony