ifima.ru

До момента написания данной статьи я довольно поверхностно знал систему Maven, однако было большое желание и даже необходимость изучить ее. Я пытался изучать Maven, читая книги (я нашел две, обе на английском языке — Maria Odea Ching, Brett Porter «Apache Maven 2 Effective Implementation» и «Maven: The Definitive Guide»), однако, известно, практический опыт позволяет ознакомиться с подобного рода вещами значительно быстрее.

Итак, шаг за шагом рассмотрим процесс автоматизации сборки проектов, написанных на PHP с помощью Maven.

Установка Maven и сопутствующих программ

Итак, сначала подготовительный этап – установка всех необходимых программ для последующей более правильной организации процесса «сборки» проекта на PHP. А именно, необходимо установить сам Maven, затем Doxygen, а также PHPDocumentator — необходим для автоматического формирования документации для вашего PHP проекта, на основе комментариев (специально оформленных) в коде. Уверен, у вас не должно возникнуть проблем с установкой всех этих программ. Единственное, не забудьте создать две переменные окружения (M2 и M2_HOME):

Переменные окружения для Maven

Также, добавьте путь к исполняемым файлам Doxygen и PHPDocumentator в переменную Path операционной системы:

Я надеюсь Вы преодолели установку всех необходимых компонентов. Кстати, чтобы проверить их работоспособность откройте новое окно командной строки Windows и наберите команды php -version, затем mvn -version, вывод должен быть примерно следующий:

Если в ответ вы получили сообщение

php (mvn) не является внутренней или внешней командой, исполняемой программой или пакетным файлом

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

В исполняемом файле PHPDocumentator phpdoc.bat я также поправил путь к интерпретатору PHP (в моем случае он входит в состав пакета Denwer):

Вместо:

Указал:

Теперь, по всей видимости, мы готовы к созданию первого проекта Maven для PHP.

Создание шаблона проекта Maven для веб-проекта на PHP

Обратите внимание, что ниже мы будем создавать шаблон проекта Maven для веб-проекта на PHP — например ваш веб-сайт. Возможно также создание шаблона проекта Maven для библиотек на PHP — например набор классов.

Для создания шаблона проекта Maven для веб-проекта на PHP5 необходимо из командной строки выполнить следующую команду:

К слову, для создания шаблона проекта Maven для библиотек на PHP5 используйте команду:

Теперь о том, что делает эта команда. Maven использует некую иерархию директорий для организации проектов. Указанная команда создает такую директорию для некоего вымышленного проекта с именем my-app. В моем случае, физически каталог для этого проекта был создан в C:\Documents and Settings\fima\my-app\. Где fima для вас будет соответствовать имени пользователя Windows. Ну а сами параметры означают следующее:

• archetypeGroupId — уникальный идентфикатор группы, объединяющей несколько шаблонов (archetype) проектов.  Это применяется как попытка ограничить область видимости, что-то вроде пакетов в языке Java. Так, «пакет» org.phpmaven может, по идее может содержать несколько шаблонов для проектов PHP. Подобных готовых групп шаблонов в Maven предостаточно, например org.apache.maven.archetypes.
• archetypeArtifactId — конкретный шаблон, который будет использован для создания вашего проекта в Maven. В нашем случае — php5-lib-archetype (стандартный шаблон для проекта на PHP). Таких готовых шаблонов для проектов Maven опять же довольно много, например maven-archetype-j2ee-simple для проектов JavaEE или maven-archetype-site-simple для создания совсем примитивных типов проектов Maven.
• archetypeVersion — задает номер версии релиза или сборки для вашего проекта.
• groupId — уникальный идентификатор группы, объединяющей несколько модулей в вашем проекте.  Так, при использовании значения org.sample, как указано выше, в нашем проекте my-app будут созданы вложенные каталоги org/sample (ниже указана полная иерархия каталогов для создаваемого нами проекта).
• artifactId — уникальный идентификатор для конкретного модуля, включенного в состав определенной группы модулей вашего проекта.

Кроме всего прочего, после создания проекта Maven в каталог с проектом будет помещен файл pom.xml, который определяет процесс сборки и документации проекта на PHP. В моем случае данный автоматически созданный файл оказался неправильным изначально. Я поправил его руками и измененный файл вы сможете найти в архиве, приложенном к данной инструкции (см. ниже). Обратите внимание, что pom.xml в приложенном архиве исправлен под версию Maven 3, если вы используете Maven версии 2, то не будет работать автоматическая генерация документации. Дело в том, что начиная с версии Maven 3 изменилась структура pom.xml для генерации документации. Для подробностей обратитесь к статье Site Generation in Maven 3.

Структура каталогов проекта на PHP в Maven

Вот так организует каталоги Maven после создания пустого проекта на PHP:

C:\Documents and Settings\fima\my-app>tree /F
Структура папок
Серийный номер тома: 988D-9402
C:.
│   pom.xml
│
└───src
    ├───main
    │   └───php
    │       └───org
    │           └───sample
    │                   app.php
    │
    ├───site
    │   ├───doxygen
    │   │       doxygen.config
    │   │
    │   └───phpdoc
    │           phpdoc.config
    │
    └───test
        └───php
            └───org
                └───sample
                        apptest.php

Каталоги предназначены для следующего:

• src/main/php — содержит исходные коды вашего проекта на PHP. Maven сгенерировал некий примерный исходный файл app.php, по сути, с бессмысленным содержимым.
• src/test/php — содержит тесты для модульного (unit) тестирования вашего проекта. Maven также сгенерировал примерный тест, использующий PHPUnit/Framework.php.
• pom.xml — находящийся в корне проекта файл pom.xml описывает объектную модель проекта (Project Object Model). Информация, содержащаяся внутри данного файла описывает проект — версию, которую мы указали при создании проекта, имя проекта и т.п.
• src/site — содержит автоматически создаваемую документацию для вашего кода на PHP (phpdoc).

Сборка проекта PHP с помощью Maven

Для того, чтобы начать сборку проекта необходимо либо уже находясь в папке с проектом, там где расположился файл pom.xml выполнить команду

либо выполнить эту же команду с указанием абсолютного пути до файла pom.xml. После завершения работы Maven создаст zip архив в каталоге target, поместив в него все PHP файлы вашего проекта. Данный архив может быть использован для загрузки вашего сайта на целевой сервер.

Документирование проекта PHP с помощью Maven

Для документирования проектов на PHP исходные коды должны быть снабжены комментариями в специально оформленном виде — phpdoc, по аналогии с Javadoc. Для автоматической генерации документации плагин Maven PHP использует две программы — PHPDocumentator и Doxygen, их вы должны были установить на первоначальном этапе (см. первый пункт данной инструкции). Не забудьте, что путь к обеим этим программам должен присутствовать в переменных окружения вашей операционной системы.

Для создания документации необходимо либо уже находясь в папке с проектом, там где расположился файл pom.xml выполнить команду

либо выполнить эту же команду с указанием абсолютного пути до файла pom.xml. После завершения работы Maven поместит созданную документацию в каталог target/site.

Полезные ссылки

1. Apache Maven — основы
2. Maven in 5 Minutes
3. Maven for PHP official website
4. Getting started with Maven for PHP
5. Writing PHP applications with Maven and Jetty

Скачать архив с проектом MVN для веб-проекта на PHP — этот архив представляет проект в состоянии после сборки и генерации документации.