Соглашения
Соглашения
Документ Стандарты написания кода описывает стандарты написания кода для проектов 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