YiiBoilerplate - это структура веб-приложения уровня предприятия. Что называется "из коробки".

Раз за разом создавая корпоративные веб-сайты для средних предприятий с использованием фреймворка Yii мы выработали стандартную структуру проекта. Изначально он базировался на следующих положениях:

1. раздельные сайты для пользовательской ("frontend") и административной ("backend") частей в целях безопасности;
2. модульная структура приложения - так, чтобы можно было бы вести независимые ветки модулей в системе контроля версий.

Эти два положения привели к значительным изменениям традиционной структуры проекта, описанной в учебнике по Yii. Они также повлияли на терминологию и привели к определению двух понятий: "точка входа" ("entry point") и "окружение" ("environment").

Мы используем эту структуру для разработки сайтов уже некоторое время, и она доказала свою высокую эффективность. Эта статья описывает полностью переработанный YiiBoilerplate и все его функции, добавленные в последнее время.

Мы надеемся, что этот шаблон будет вам полезен.

Прежде всего мы должны заметить, что YiiBoilerplate не является ни библиотекой, ни новым фреймворком. Это исключительно шаблон, который используется при старте проекта. Поэтому нет смысла думать об "обновлениях" или "будущих версиях" как только вы запустили на нём свой проект - просто дорабатывайте его так, как вам необходимо.

• PHP 5.4. Уже даже стабильная версия Debian, известная своим консерватизмом в вопросах обновлений, содержит версию 5.4. Поэтому либо обновляйте PHP до версии 5.4., если это возможно, либо прекращайте пользоваться хостингом с устаревшими версиями PHP.
• Желательно: поддержка работы архивов PHAR из консоли (она также должна быть включена в php.ini).
• Опционально: Java для запуска Selenium.
• Опционально: Virtualbox и Vagrant для быстрого развёртывания локальных окружений.

1. Установить Vagrant (не описывается в данной статье).

2. Установить Virtualbox (не описывается в данной статье).

3. Если у вас уже установлен PHP 5.4+ (а это имеет смысл из-за новых возможностей), у вас есть всё необходимое для YiiBoilerplate.

4. Теперь просто клонируйте репозиторий YiiBoilerplate:

   git clone Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.:clevertech/YiiBoilerplate.git <yourprojectname>
   

5. Изнутри клонированной директории запустите и дождитесь завершения:

   vagrant up
   

   Vagrant может жаловаться на различие версий гостевых дополнений Virtualbox'а и самого Virtualbox'а. Это решается запуском vagrant plugin install vagrant-vbguest, и это единственный не очевидный шаг, с которым вам придётся столкнуться.

6. Готово. По адресу http://localhost:8080/ будет располагаться пользовательская часть вашего сайта, по http://localhost:8081/ - административная.
   Можно начинать работать.
   Не забывайте выполнять команду выключения виртуальной машины vagrant halt перед тем, как выключить свою рабочую станцию, Virtualbox может не выключиться пока не получит команду kill -9.

Для выполнения всех настроек вручную можно обратиться к файлам carcass/vagrant/prepare-precise64.sh и carcass/vagrant/setup-app.sh.

Мы интегрировали практически все инструменты из проекта PHP QA Tools в систему сборки проектов Phing.

Чтобы получить отчёты всех возможных статических анализаторов кода вашего проекта плюс документацию по API, просто наберите:

bin/phing

В результате в папке reports будут созданы следующие отчёты:

• Отчёт о нарушениях в стиле кода в формате Checkstyle от PHP Code Sniffer;
• Отчёт о покрытии кода тестами в формате Clover от PHPUnit
• Отчёт о дублировании кода в формате XML от PHP Copy-Paste Detector
• Отчёт об объёме кода в формате XML от PHPLOC
• Отчёт о различных проблемах в формате XML от PHP Mess Detector
• Отчёт в XML от PDepend
• Две схематичных метрики кода в формате SVG от PDepend
• Отчёт о покрытии кода тестами в формате HTML от PHPUnit
• Дерево проекта в виде HTML страниц со всем кодом и выявленными проблемами от PHP Code Browser
• и, наконец, автоматически сгенерированная документация по API в HTML формате от ApiGen.

Мы уверены, что этого набора отчётов будет достаточно для понимания состояния, в котором находится ваш проект.
Понятно, что для генерации отчёта о покрытии кода тестами будут выполнены все модульные тесты. Таким образом, в качестве побочного эффекта, вы получите регрессионное тестирование (надеемся, что ваши тесты выполняются сравнительно быстро).

Давайте теперь заглянем внутрь.

YiiBoilerplate был разработан для веб-приложений среднего размера и любого назначения, разрабатываемых на базе фреймворка Yii. Под "средним размером" мы понимаем от 10 до 100 уникальных маршрутов. Опять же поддерживается два уровня тестов для разработки через тестирование: приёмочные тесты с помощью Behat, а также модульные и интеграционные тесты с помощью PHPUnit.

По большому счёту, YiiBoilerplate - это набор папок и файлов, которые вы загружаете в вашей системе контроля версий в качестве первого коммита. Он представляет собой каркас сайта, состоящий из пустой заглавной страницы пользовательской части и административной части с простейщим UI и уже подключённым механизмом аутентификации на основании паролей.

Содержание каждой папки подробно описано в файле README.md внутри соответствующей папки.

1. backend

   Точка входа в административную часть приложения.

2. bin

   Двоичные (бинарные) файлы, которые используются приложением. В том числе yiic, phing, phpunit и т.п. Заметим, что хотя большинство файлов устанавливается через Composer, yiic и selenium устанавливаются вручную и не должны быть изменены или удалены.

3. carcass

   Файлы конфигурации для различных дополнительных инструментов, используемых в проекте. Например, скрипты для Vagrant или настройки стиля кода для CodeSniffer.

4. common

   Эта папка в точности повторяет традиционную папку protected в автоматически создаваемом проекте Yii. Весь код, общий для всех точек входа должен помещаться в папку common. Код, специфичный для административной, пользовательской или консольной частей, должен помещаться соответственно в backend, frontend или console.

5. console

   Точка входа для консоли, к которой подключается yiic. Большинство кода - это миграции для БД в подпапке console/migrations.

6. frontend

   Точка входа для пользовательской части сайта.

7. reports

   Все отчёты о статусе проекта, качестве кода и т.п. Документация по API от APIGen тоже хранится здесь. Вначале этой папки нет, она создаётся при необходимости.

8. tests

   Все ваши тесты. Подробнее см. файл README.md внутри папки.

9. vendor

   Все сторонние приложения, установленные через Composer, в том числе Selenium. Эта папка тоже создаётся при необходимости.

YiiBoilerplate содержит в себе инструментарий Vagrant, который вы можете использовать по своему усмотрению. Vagrantfile настроен на использование образа precise64, который представляет из себя чистый образ Ubuntu 12.04, подготовленный для Virtualbox.

Т.к. YiiBoilerplate это простейшее веб-приложение, мы подготовили набор скриптов для для развёртывания виртуальной машины Vagrant. Они находятся в папке carcass/vagrant. Два скрипта для Vagrant можно использовать как примеры для автоматического развёртывания YiiBoilerplate на *nix системах:

• prepare-precise64.sh - этот скрипт устанавливает на Ubuntu 12.04 необходимый стек технологий для стандартного приложения с использованием базы данных: PHP 5.4, apache, mysql, git и т.д., а также создаёт саму базу данных.
• setup-app.sh - скрипт установки приложения на подготовленную систему: создание файлов конфигурации, необходимых для работы приложения папок, а также удовлетворение всех зависимостей.

Вы можете самостоятельно их изучить, они ничуть не трудны для понимания.

Заметим, что в установке по умолчанию после каждой команды vagrant provision необходимо дождаться завершения выполнения трёх вызовов apt-get update. Это занимает достаточно много времени.

Чтобы избавиться от повторения этих долгих процедур, вы можете упаковать виртуальную машину, созданную после запуска vagrant up в свой образ Vagrant и использовать его в дальнейшем вместо оригинального precise64. В этом случае не забудьте удалить prepare-precise64.sh из скриптов настройки окружения в Vagrantfile.

Если из написанного выше вы не слова не поняли, приглашаем вас к изучению документации по vagrant box repackage и документации по инициализации на сайте Vagrant.

Все сторонние компоненты YiiBoilerplate, включая собственно Yii, управляются с помощью Composer. Вы получаете Behat+Mink+MinkExtension, PHPUnit, полный набор инструментов для контроля качества кода PHP Quality Assurance toolchain, Phing, ApiGen, Yii и YiiBooster в качестве зависимостей. В Composer'е есть даже Selenium, поэтому он тоже будет установлен.

Использование Composer'а значительно уменьшает объём кода приложения, который необходимо хранить в репозитории. Чтобы быть уверенным в том, что у каждого разработчика команды установлены одинаковые версии сторонних приложений, Composer создаёт специальный файл composer.lock, который можно закоммитить в репозиторий вместо всей папки vendor. Содержимое этого файла в точности сообщает Composer'у какие версии приложений должны быть использоваться для данного приложения. В репозитории YiiBoilerplate есть такой файл, так что можно быть уверенным, что по крайней мере разработчикам удалось запустить шаблон приложения с использованием всех перечисленных инструментов.

composer.json был настроен таким образом, чтобы все исполняемые файлы хранились в папке bin.

Возможно вам понадобится система сборки вашего приложения, поэтому мы включили в YiiBoilerplate Phing. Разработанный нами управляющий скрипт для Phing позволяет получить полный набор отчётов о статусе вашего приложения.

Результат выполнения скрипта, запускаемого командой bin/phing, был описан ранее.

Обратите внимание, что перечень папок с исходным кодом для каждого инструмента, используемого Phing'ом, описан в отдельном файле вида carcass/filesets.xml. Все папки, исключённые из анализа, вам надо будет добавить вручную в основной сборочный файл. Также файл придётся обновить при изменении структуры проекта.

Традиционное консольное приложение Yii было перенесено в папку bin. Это было сделано в целях безопасности, чтобы использовалась только встроенная в YiiBoilerpalte консоль, т.к. Composer устанавливает все исполняемые файлы в одну и ту же папку.

Папка console полностью предназначена для обслуживания точки входа в приложение через консоль. Поэтому, чтобы выполнить какую-либо команду, встроенную в консоль или определённую в console/commands вашего приложения, необходимо запускать bin/yiic <command> из корня приложения (вместе более короткой ./yiic).

Мы думаем, что это вполне приемлемый компромисс.

В качестве движка приёмочных тестов мы использовали комбинацию Behat + Mink + MinkExtension поверх Selenium2.

Это на сегодняшний день пожалуй лучший набор инструментов для приёмочного тестирования приложений на PHP. Синтаксис тестов позволяет вам, вашим тестировщикам или даже клиентам, описывать приёмочные тесты на человеко-понятном языке. Selenium использует обычный браузер для работы с графическим пользовательским интерфейсом вашего приложения и делает это сумасшедше быстро, так что вам даже не надо пользоваться браузерами без графических оболочек (такими как phantomJS или Zombie).

Все необходимые настройки уже собраны в файле behat.yml. Для вашего удобства он помещён в корневую папку, поэтому вы можете запускать Behat без необходимости указывать путь до файла конфигурации в командной строке. Необходимо сделать только разместить файл behat-local.yml в корневую папку с кодом приложения, в котором надо определить непереносимые настройки: базовый URL для подклчючения Mink к вашему приложению. Если вы используете виртуальную машину Vagrant, инициализирующий скрипт сам поместит файл behat-local.yml в нужное место. Можете взглянуть на файл carcass/vagrant/behat-local.yml, чтобы понять что от вас требуется.

Если вы выполняли базовую установку с использованием Selenium, необходимо запустить скрипт bin/selenium, который полностью займёт один терминал.

Все ваши тесты для пользовательской части приложения должны быть помещены в tests/specs/frontend. Все они могут быть выполнены одной командой bin/behat -p frontend.

Тесты для административной части должны быть в tests/specs/backend. Они запускаются командой bin/behat -p backend.

Оба набора описаний используют единый класс контекста, расположенный в tests/specs/contexts/FeatureContext.php. Все шаги при тестировании должны быть описаны в этом файле. Обратите внимание, что класс FeatureContext - это только точка старта, ничто не мешает вам настраивать приёмочные тесты так, как считаете нужным.

Для модульного тестирования мы включили в зависимости Composer'а библиотеку PHPUnit. Его исполняемые файлы находятся с папке bin, как и все остальные исполняемые файлы. По умолчанию все тесты выполняются пакетно, поэтому они должны работать быстро. Конфигурационный файл phpunit.xml расположен в корневой папке с кодом, поэтому можно запускать тесты командой bin/phpunit без необходимости указывать путь до файла настроек.

Файл настроек, включённый в YiiBoilerplate, не содержит никакого покрытия кода тестами. Чтобы определить это покрытие необходимо использовать одну из целей Phing под названием coverage таким образом: bin/phing coverage, в котором настройки покрытия кода указываются с использованием ключей командной строки.

Нашей целью было сделать инструмент для чисто модульного тестирования. Для интеграционного тестирования мы подготовили скрипт начальной загрузки PHPUnit, который выполняет общую инициализацию приложения YiiBoilerplate. Его настройки изложены в файле common/bootstrap.php, который также содержит некоторые хитрости по аналогии с yiit.php. Этот скрипт инициализации по сути является четвёртой точкой входа в приложение.

Получается, что когда вы выполняете команду:

bin/phpunit --bootstrap carcass/phpunit.bootstrap.php

вы выполняете все тест-кейсы в окружении, в котором определён класс Yii, а также произведена стандартная начальная настройка. Таким образом вы можете спокойно инициализировать веб-приложение так, как считаете нужным, и с любой конфигурацией тестов.

Для административной части приложения мы включили в зависимости Composer'а другую нашу библиотеку: YiiBooster, а также добавили настройки, позволяющие подключить её к проекту.

Так что вы получаете весь функционал YiiBooster для разработки пользовательского интерфейса административной части вашего приложения. Возможности библиотеки подробно описаны в документации YiiBooster.

Пользовательская часть, напротив, представляет собой пустую страницу на основе HTML5Boilerplate. По нашему опыту пользовательская часть каждого веб-приложения абсолютно уникальна, поэтому мы считаем, что применять для её оформления стандартный Twitter Bootstrap не совсем уместно.

Весь код по умолчанию распространяется под лицензией BSD, как и все опен-сорс разработки Clevertech.

Так как со временем внутри шаблона всё может поменяться, можете считать, что он является общественным достоянием. Мы никак не ограничиваем изменения в YiiBoilerplate для ваших нужд.

Чтобы в полной мере использовать автодополнение в phpStorm, мы применили несколько хитростей для игнорирования некоторых сторонних библиотек.

1. Мы используем наш собственный класс Yii, чтобы задействовать кнопку F4 для вызова Yii::app(). Однако это приводит к повторяющимся значениям параметров, на что phpStorm "ругается".

   1. В меню File -> Settings -> PHP в секции Include Path найти запись, оканчивающуюся на yiisoft/yii и заменить её на yiisoft/yii/framework.
   2. Аналогичным образом надо заменить clevertech/yii-booster на clevertech/yii-booster/src.
   3. В меню File -> Settings -> File Types в секции Ignore files and folders добавить (дословно) строку ;framework/Yii.php;tests/fakes/Yii.php.

2. Кроме того, Behat, устанавливаемый через Composer, содержит класс FeatureContext, который конфликтует с нашим одноимённым классом. В меню File -> Settings -> PHP в секции Include Path надо найти запись, заканчивающуюся на behat/behat и добавить к ней src. Это исключит код тестов из индекса Behat.

Обратите внимание, что из-за механизма индексации phpStorm вам надо будет либо менять пути PHP каждый раз после внесения изменений в composer.json, либо отключить автоматическую переиндексацию всех установленных через Composer библиотек.

Замечание об использовании phpStorm для разработки приложений на базе Yii: если вы хотите, чтобы компоненты приложения были доступны по нажатию F4 на имени компонента в переменной, например как здесь: Yii::app()->request, вам необходимо добавить блоки @property в определение классов вашего приложения с указанием связи названия класса компонента и его идентификатора. Это также улучшает понимание кода человеком.