Соглашения

Соглашения

Документ Coding Standards описывает стандарты написания кода для проектов Symfony и внутренних и сторонних пакетов. Этот документ описывает стандарты написания кода и соглашения, используемые в базовом фреймворке, чтобы сделать его более целостным и предсказуемым. Мы рекомендуем вам следовать им в вашем коде, но вы не обязаны это делать.

Имена методов

Когда объект имеет "основную" множественную связь с относящимися к ней "вещами" (объектами, параметрами, ...), то имена методов нормализуются:

  • get()
  • set()
  • has()
  • all()
  • replace()
  • remove()
  • clear()
  • isEmpty()
  • add()
  • register()
  • count()
  • keys()

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

  • CookieJar имеет множество объектов Cookie;
  • сервис Container имеет множество сервисов и параметров (так как сервисы - главная связь, соглашение именования используется для этой связи);
  • консоль Input имеет множество опций. "Основной" связи нет, поэтому соглашение именования не применяется.

Для многих связей, где соглашение не применяется, должны быть использованы следующие методы (где XXX - это имя связанной вещи):

Главная связь Другие связи
get() getXXX()
set() setXXX()
не доступна replaceXXX()
has() hasXXX()
all() getXXXs()
replace() setXXXs()
remove() removeXXX()
clear() clearXXX()
isEmpty() isEmptyXXX()
add() addXXX()
register() registerXXX()
count() countXXX()
keys() не доступна

Note

Несмотря на то, что "setXXX" и "replaceXXX" очень похожи, существует заметная разница: "setXXX" может заменять или добавлять новые элементы в отношения. А "replaceXXX" - не может. Если неопознанный ключ передаётся "replaceXXX", он должен вызвать исключение.

Депрекации

Время от времени, некоторые классы и/или методы в фреймворке устаревают; это случается, когда реализация функции не может быть изменена из-за проблем ОС, но мы всё равно хотим предложить "Лучшую" альтернативу. В этом случае, старая реализация может быть просто устаревшей.

Функция помечается, как устаревшая, путём добавления phpdoc @deprecated к связанным классам, методам, свойствам, ...:

1
2
3
/**
 * @deprecated начиная с версии 2.8, будет удалена в 3.0. Используйте XXX вместо этого.
 */

Сообщение об устарении должно обозначать версию, когда класс/метод усарел, версию, когда он будет удалён, и, если возможно, как была заменена функция.

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

1
@trigger_error('XXX() устарела начиная с версии 2.8 и будет удалена в 3.0. Используйте XXX вместо этого E_USER_DEPRECATED);

Без `@-silencing operator`_, пользователям нужно будет выключать уведомления об устарении. Заглушение меняет это поведение и позволяет польователям включать их, когда они готовы справиться с ними (добавив пользовательский обработчик ошибок, как тот, что используется панелью инструентов веб-отладки или PHPUnit bridge).

Когда устаревает целый класс, вызов trigger_error() должен быть помещён между пространством имён и заявлениями об использовании, как в этом примере из ArrayParserCache:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
namespace Symfony\Component\ExpressionLanguage\ParserCache;

@trigger_error('The '.__NAMESPACE__.'\ArrayParserCache class is deprecated since version 3.2 and will be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.', E_USER_DEPRECATED);

use Symfony\Component\ExpressionLanguage\ParsedExpression;

/**
 * @author Adrien Brault <[email protected]>
 *
 * @deprecated ArrayParserCache класс устарел с версии 3.2 и будет удалён в 4.0. Используйте класс Symfony\Component\Cache\Adapter\ArrayAdapter вместо этого.
 */
class ArrayParserCache implements ParserCacheInterface

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.