Соглашения

Документ Стандарти написання коду описывает стандарты написания кода для проектов 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, пользователям нужно будет выключать уведомления об устарении. Заглушение меняет это поведение и позволяет польователям включать их, когда они готовы справиться с ними (добавив пользовательский обработчик ошибок, как тот, что используется панелью инструентов веб-отладки или 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 <adrien.brault@gmail.com>
 *
 * @deprecated ArrayParserCache класс устарел с версии 3.2 и будет удалён в 4.0. Используйте класс Symfony\Component\Cache\Adapter\ArrayAdapter вместо этого.
 */
class ArrayParserCache implements ParserCacheInterface
    