in Профессиональное

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

Пакет – прежде всего это директория, которая имеет строго определенную структуру и может содержать все что угодно (от классов, до контроллеров и 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

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

Write a Comment

Comment

*

  1. Хороша стаття. Може напишете ще про то як перекладати бандли XLIFF :).

    • Боюсь, статья несколько устарела. Обратите внимание на обновляемый перевод документации: http://symfony-gu.ru/documentation/ru/html/index.html

      p.s. “як перекладати бандли XLIFF” перетолмачить на нашенскую мову не смог ) Если можно – конкретизируйте вопрос 😉