hudson@work » best practices

Symfony 2: пакеты, практические рекомендации

hudson — Tue, 15 Feb 2011 07:58:29 +0000

Пакет – прежде всего это директория, которая имеет строго определенную структуру и может содержать все что угодно (от классов, до контроллеров и web-ресурсов). Не смотря на то что пакеты очень гибки, вы должны следовать некоторым рекомендациям (best practices), если вы хотите выложить его в общий доступ. Об этих практиках мы и поговорим ниже:

Наименование пакета

Пакет – это, помимо всего прочего, также пространство имен. Пространство имен должно соответствовать стандартам совместимости PHP 5.3 для пространств имен и наименований классов: они должны начинаться с сегмента “поставщика” (вендора), содержать несколько сегментов категорий (в том числе может не содержать ни одного) и оканчиваться коротким наименованием пространства имен, которое должно, в свою очередь, завершаться суффиксом Bundle.

Пространство имен становится пакетом как только вы добавите в него класс пакета (bundle class). Наименование класса пакета должно соответствовать нескольким нехитрым правилам:

Использовать только буквы, цифры и подчерк;
Использовать ВерблюжийРегистр (aka CamelCase) для имени
Использовать описательные и короткие наименования (не менее 2х слов)
Использовать в качестве префикса наименование вендора (и опционально – категории пространства имен)
Использовать суффикс Bundle.

В таблице ниже приведены несколько примеров правильных пространств имен и наименований классов для пакетов:

Пространство имен	Наименование класса
`SensioBundleBlogBundle`	`SensioBlogBundle`
`SensioBundleSocialBlogBundle`	`SensioSocialBlogBundle`
`SensioBlogBundle`	`SensioBlogBundle`

По договоренности, метод getName() класса в пакете должен возвращать имя класса.

Структура директорий

Базовую структуру директорий пакета HelloBundle можно представить следующим образом:

XXX/...
    HelloBundle/
        HelloBundle.php
        Controller/
        Resources/
            meta/
                LICENSE
            config/
            doc/
                index.rst
            translations/
            views/
            public/
        Tests/

Структура директорий XXX отражает структуру пространства имен пакета.

Следующие файлы являются обязательными:

HelloBundle.php;
Resources/meta/LICENSE: текст лицензии на код пакета;
Resources/doc/index.rst: корневой файл документации пакета.

Замечание: следование этим соглашениям обеспечивает работу средств автоматизации.

Глубина под-директорий должна быть минимально необходимой для используемых классов и файлов (максимум 2 уровня). Больший уровень вложенности может быть использован для малозначимых или же редкоиспользуемых файлов.

Дирктория пакета предназначается только для чтения. Если вам необходимо писать временные файлы – вы можете сохранять их в директории cache/ или log/. Вы можете генерировать файлы в директории пакета при помощи различных инструментов, но только в том случае, если генерированные файлы будут частью репозитория.

Следующие классы и файлы имеют определенное расположение:

Тип	Директория
Контроллеры	`Controller/`
Файлы с переводами	`Resources/translations/`
Шаблоны	`Resources/views/`
Модульные и функциональные тесты	`Tests/`
Web-ресурсы (доступные публично)	`Resources/public/`
Конфигурация	`Resources/config/`
Команды	`Command/`

Классы

Структура директорий пакета используется как иерархия пространства имен Например, HelloController контроллер находится по пути Bundle/HelloBundle/Controller/HelloController.php и полное имя класса будет BundleHelloBundleControllerHelloController.

Все классы и файлы должны соответствовать стандартам кодирования Symfony2.

Некоторые классы следует рассматривать как фасады (facades) и стараться делать их как можно более короткими, например Commands, Helpers, Listeners и Controllers.

Классы, которые подключаются к Event dispatcher’у должны иметь суффикс Listener.

Классы исключений должны быть расположены во сложенном пространстве имен Exception.

Вендоры

Пакет не должен включать сторонних PHP-библиотек. Вместо этого они должны располагаться в стандартной директории Symfony2, доступной автозагрузчику. Также пакет не должен включать сторонних библиотек на JavaScript, CSS или на других языках.

Тесты

Пакеты должны комплектоваться набором тестов на PHPUnit и расположенными в директории Tests/. Тесты должны следовать следующим принципам:

Тестовый набор должен выполняться простой командой phpunit из демо-приложения;
Функциональные тесты должны быть использованы только для тестирования ответов (response output) и профильных данных, если таковые имеются;
Покрытие кода должно составлять не менее 95% кода вашего пакета.

Замечание: тестовый набор не должен содержать скрипта AllTests.php, но должен полагаться на наличие файла phpunit.xml.dist.

Документация

Все классы и функции должны быть документированы в стиле PHPDoc.

Полная документация также должна быть представлена в формате reStructuredText, и располагаться в директории Resources/doc/; наличие файла Resources/doc/index.rst – обязательно!

Контроллеры

Контроллеры в пакете не должны наследоваться от класса Controller. Они должны реализовывать интерфейс ContainerAwareInterface или наследоваться от класса ContainerAware.

Замечание: Если вы посмотрите на методы класса Controller, вы заметите что они представляют собой “ярлычки” для упрощения изучения.

Шаблоны

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

Файлы переводов

Если пакет содержит переводы сообщений, они должны быть определены в формате XLIFF;

If a bundle provides message translations, they must be defined in the XLIFF format; домен должен располагаться после имени пакета (bundle.hello).

Пакет не должен переопределять уже существующие сообщения из других пакетов.

Конфигурация

Конфигурация пакета должна использовать строенный механизм Symfony2. Пакет должен предоставлять все его базовые настройки в виде XML.

Оригинал тут http://docs.symfony-reloaded.org/guides/bundles/best_practices.html

Перевод как обычно авторский )

О «symfony best practices»

hudson — Sun, 07 Mar 2010 04:38:30 +0000

Кросспост моего хабратопика.

Nicolas Perriault представлял на SymfonyDay’09 презентацию “30 Symfony Best Practices”. Кое-что из его практик очевидно (было мне известно), кое-что не было. Но есть две практики, которые мне совершенно не видятся как “best”. О них я и хочу поговорить.

Итак:

#4
Никаких экземпляров Criteria (Propel) или Doctrine_Query, SQL запросов и любой ORM/RDBMS специфики не должно быть ни в шаблонах ни в экшенах (actions);
Чем сильнее вы привяжете модель к контроллерам и видам, тем более инертным к изменениям будет ваш бэкэнд.

Далее следует несколько примеров:

// ПЛОХО
public function executeRecentProducts( sfWebRequest $request )
{
    $this->products = Doctrine::getTable( 'Product' )
        ->createQuery( 'p' )
        ->where( 'p.is_published = 1' )
        ->orderBy( 'published_at DESC' )
        ->limit(10)
        ->execute();
    // Плохо, получаем Doctrine_Collection
}

// ЧУТЬ ЛУЧШЕ
public function executeRecentProducts( sfWebRequest $request )
{
    $this->products = Doctrine::getTable( 'Product' )
        ->createQuery( 'p' )
        ->where( 'p.is_published = 1' )
        ->orderBy( 'published_at DESC' )
        ->limit(10)
        ->fetchArray();
    // Уже лучше, Array
}

// ХОРОШО
public function executeRecentProducts( sfWebRequest $request )
{
    $this->products = ProductTable::getRecent( $max = 10, $published = true );
    // Array, идеально ))
}

Итак, что же предлагает Николас? С тем что нужно избегать Doctrine_Query и т.п. в видах и действиях – с этим я согласен. Но он также предлагает передавать во view только массивы (см. примеры выше). На словах выглядит неплохо, но зачастую может возникнуть проблема с подтягиванием связанных записей (1:n или n:n). Опять же, подтягивать в виде заранее не выбранные при джойне записи – это можно сказать “плохой тон” разработки. Но с другой стороны это происходит совершенно прозрачно для разработчика (и при необходимости отлавливается через webDebug).

Другой неприятный момент в передаче массивов в вид в том, что какое-то из передаваемых значений может потребовать предварительной обработки перед выводом, что придется выполнять явно в действии или в *Table классе. Если же у нас есть объект, то мы можем вызвать например метод getMyField() вместо getField().

#25
Избегайте помещения под версионный контроль любые из генерированных классов вида Base*, в особенности, если вы хотите писать плагины для многократного использования или же хотите перераспределять вашу работу. Почему? Возможно что-то захочет расширить ваши классы модели или же добавить к ним behavior другой.

Что меня беспокоит здесь? То, что в репозитории не хранится целостное приложение. Т.е. модель конечно есть, схема есть. Но отсутствуют классы, от которых наследуется ваша модель. Таким образом, осуществляя вынос вашего приложения на production сервер, вы всегда должны помнить, что помимо update’а кода, выполнения миграции (которая еще не факт что выполнится при отсутствии Base* классов), выполнения дополнительных процедур, присущих конкретному релизу, вы должны будете еще пересобрать и модель. Согласитесь, еще один элемент сакральных знаний, который со временем (особенно на больших проектах) переходит в область чего-то почти магического.

В Doctrine 2.0 обещают уйти от наследования Base* классов, так что, возможно, скоро эта практика утратит актуальность. Но пока мы имеем Doctrine 1.2 ))

Ну что, коллеги, а вы что думаете об этих двух практиках? Как поступаете изо дня в день?