We assume that you have a running setup of both, php and maven. That means that you can run both, "php" and "mvn" via command line. If you cannot run them you may read our prepare site
We assume that you use the command line tool (mvn) and not use any complex IDE. Some IDEs (netbeans, eclipse) already have built in support for maven. There is another tutorial section later on you may read for IDE support. We recommend that you should at least read the tutorials about the mvn command line tool since they are based on maven itself.
Before starting some background information on maven:
Maven identifies your project by several IDs. However this is maven related and you should follow them as this is a good choice for any project. First of all there is a groupId. This can be used as your company or organization informational id. In Java (what maven primary targets) and in www simple domain names are used. So if you are owning domain "www.mycompany.org" simply use the groupId "org.mycompany" or "org.mycompany.php". Think of the groupId being some kind of namespace to identify projects.
The project itself is identified by the artifactId. This id must be unique within the groupId. And it should be unique world-wide. The groupId and artifactId are divided by colons. Let us make a simple example:
In this example you have two projects. Both of them have an artifactId called "core". This setup will work but it may be confusing for project users. So you should think of the following naming:
The third important identification of your project is the version. It follows the world wide convention <major>.<minor>.<fixlevel>-<extra>. You should read maven documentation to get more deeper inside since version naming follows some conventions. This is important to find newer versions than those already installed. You may already assume that version 2.4 is greater than version 1.9.5. In short words: If the numeric parts of the version number are identical you should assume the following:
So a complete identification of your project may be: org.mycompany:php-core:1.4.6-SNAPSHOT
There are two ways to create a project. You can either create it from scratch or use an archetype. Archetypes are some kind of project template. Creating projects from scratch requires more work.
There are multiple archetypes you may use. To create a library project simply type the following command:
mvn archetype:generate \ -DarchetypeGroupId=org.phpmaven \ -DarchetypeArtifactId=php5-lib-archetype \ -DarchetypeVersion=2.0-SNAPSHOT \ -DgroupId=org.sample \ -DartifactId=my-app \
This command will create a new folder and put everything you need to startup developing inside it.
Hint: You may find various archetypes listed at the following site: archetypes overview
Create the following directory layout:
my-app |-- pom.xml `-- src |-- main `-- php `-- org `-- sample `-- app.php |`-- test `-- php `-- org `-- sample `-- apptest.php |`-- site `-- site.xml
The contents of the files will be discussed in the following chapter.
As you already see it is a convention that the main folder "my-app" equals the artifactId. You should always follow this convention.
The main project file for maven is the pom.xml. Here is where all the magic goes. Maven will always read this file to fetch the work it will have to do. So it is important that maven itself finds the file. Every subsequent maven command should always be invoked while the folder "my-app" is the current working directory.
Note: We will only discuss the main contents we need for php projects here. There may be archetypes placing some more constructs within the pom.xml. For details you should read the maven documentation.
Have a look at the main contents of the pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.sample</groupId>
<artifactId>my-app</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>php</packaging>
<name>Sample PHP 5 library project</name>
<build>
<plugins>
<plugin>
<groupId>org.phpmaven</groupId>
<artifactId>maven-php-plugin</artifactId>
<version>2.0-SNAPSHOT</version>
<extensions>true</extensions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.0</version>
<inherited>true</inherited>
<configuration>
<reportPlugins>
<plugin>
<groupId>org.phpmaven</groupId>
<artifactId>maven-php-plugin</artifactId>
<reportSets>
<reportSet>
<reports>
<report>phpdocumentor</report>
</reports>
</reportSet>
</reportSets>
</plugin
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>2.10</version>
<reportSets>
<reportSet>
<reports>
<report>report-only</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</reportPlugins>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>org.phpunit</groupId>
<artifactId>phpunit5</artifactId>
<version>3.3.9</version>
<scope>test</scope>
</dependency>
</dependencies>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
</project>
At first you will find the three IDs we mentioned. They will identify your project as org.sample:my-app:0.0.1-SNAPSHOT. The packaging tag is very important to let maven identify your project as a php-maven project. Maven itself does only understand project type "pom". So it needs plugins to identify more project types. But as you see this is fairly simple. Within the build section you will find the reference to the php-maven plugin. Without this reference maven does not understand your project and will complain to use it at all.
The build section contains another plugin, the site plugin. We will discuss this later on in the documentation tutorial. For know simply think of "The tutorial says: I need it, so I copy and paste it".
Have a look at the dependencies section. This section tells maven that we need another project. This project is identified as org.phpunit:phpunit5:3.3.9. What does it mean? maven will manage dependencies to other projects. It does all the magic, for example downloading from remote repository, for us. We do not have to know where to get it or how to install it. We only may assume that it is available in any of the configured repositories. PHPUnit itself is indeed available in the official repository where maven already found the phpmaven plugin. As soon as maven feels the need to download phpunit it will do it.
The scope:test is another hint for maven. Maven itself will always divide the real-world sources (your project itself) and the test-world sources. Testing is important during development time and release time. But it is not important to run your project or to install a website. So this dependency tells maven: we need phpunit for testing.
We do not go more deeper inside since this is only an example. Keep in mind that every php file will be placed within the folder src/main/php. We will discuss developing your project later on.
Phpmaven will assume that every php file placed within src/test/php and with suffix "test.php" will represent a test file that should be executed by phpunit.
<?php
/**
* The foo test class
*
* @author mepeisen
*/
class FooTest extends PHPUnit_Framework_TestCase
{
/**
* tests the bar function
*/
public function testBar()
{
include "org/sample/app.php";
$this->fail('we will fail');
}
}
You may assume that PHPUnit is already included. So you do not need additional includes. And you may assume that the include path is fixed so that your php classes are already available. As you see the inclusion will work.
There is nothing more we will say. All you need to do know is creating test cases for your application.