PayPal - The safer, easier way to pay online!

[ Previous | TOC | Next ]

Creation phase

Preamble

We assume that you have a working project installation. Everything is up to you to develop your library or web project. For details you should read the previous chapter.

Directory layout

There are some folders where all the files are placed. You should always follow this directory layout.

src/main/php

Within this folder you will find the "static" php-files (and only them). For clean library and web projects you may organize them as you want. But for clean development you should follow the conventions to place only one class per file and name the files according to your class. Namespace may become folders and class/interface names the file name. For example: src/main/php/foo/Bar.php should lead to class/interface \foo\Bar.

Using frameworks and autoloaders there may be alternative directory layouts. In future versions of phpmaven there may be more restrictive directory layouts. For example become a features member of the phpmaven community we will recommend some standards. The (possible) standards we are applying to the community will be presented later on. As we will support all kind of projects there will be always a way to start projects without applying these standards.

src/test/php

The test folder contains phpunit test classes. Every file with suffix "test.php" contains a single test class. The tests will be executed during test goal. We will explain testing in another step of this tutorial.

src/main/resources

Here all non-php resources go. Currently this includes css and js files as well as html files. Note: This may be changed in future versions of phpmaven. But do not mind yet. Placing those files in the resources directory will always work too.

Maven will expect the resource folder to be simply copied to the resulting project folder. You may apply filtering to get some kind of dynamic results from maven.

src/test/resources

As you may already assume this folder is the important folder for all non-php files you need during testing.

src/site

This folder represents the project site. Every project should have a clean project site. On this site you will be able to present your project. This includes documentation and manuals explaining the usage as well as api docs and some other things.

If you think of "no, not yet" let us tell you that there will be situations you get new team members or that you have to revisit your project after one year of inactivity. You will be very glad to see a good documentation in future.

target

This folder contains all "results" of maven and phpmaven itself. It is meant to be ignored by any concurrent version tool. So you should always include this folder in .gitignore svn.ignore .cvsignore and similar files/ properties. If you did not start a build this folder is not available. It will be created automatically as soon as maven requires it.

target/classes

Phpmaven will copy the resources and php files into this directory. So this folder is the main one to be used for script execution.

target/test-classes

As Maven always divides the project sources themselves from test sources it will introduce this folder to copy all test classes and test resources to.

target/php-deps and target/php-test-deps

If your project contains dependencies (at least it will have a dependency to phpunit itself) phpmaven will use this folders. "php-deps" will be used for all compile-dependencies and "php-test-deps" will be used for all test-dependencies. Do not mind the wording here. Of course php does not need a compilation in meaning of Java or C#.

In current version of php-maven it will extract all dependencies to the directories. You should assume to find them on include path. Future versions of phpmaven will give you finder control about the dependency handling as this may be needed by frameworks and to minimize disk usage. For example most libraries will work by simply putting the phar archive on include path.

target/site

This folder will conatin the generated project site and project documentation.

Respecting the lifecycle

As long as you do not use an IDE with built in maven support you will have to invoke the maven lifecycle manually.

To clean up previous results you should invoke the following command:

mvn clean

To build your project you should invoke:

mvn compile

To test your project invoke:

mvn test

To generate the project site you should invoke:

mvn site

Explanation or HowTo: Automatically return project version

You may think this is some kind of overhead. Of course for our first project this is overhead. But: The maven guys thought of many situations and got a lifecycle that fits our need. This may cause some small overhead for you. Using some IDEs like eclipse or netbeans will execute those maven commands as soon as you change a source file and save it. So you do not see any difference from know although there are new folders created by maven.

But we do we need this overhead? Let us build a small example. Let us assume the library itself will have a class called Version. This class should return the project version. But we do not want to manually edit the files. Why do we need it as we already set the version number in our pom.xml? First we will create our class in src/main/php/myapp/Version.php:

<?php

namespace myapp;

/**
 * Version class to get the library version
 */
class Version {
    
    /**
     * Returns the library version as string.
     *
     * @return string The library version.
     * @throws Exception thrown if the version is not known
     */
    public static function get() {
        $file = __DIR__.'/version.txt';
        if (!file_exists($file)) {
            throw new Exception('Version unknown. version.txt does not exist.');
        }
        $version = file_get_contents($file);
        if ($version == '${version}') {
            throw new Exception('Maven lifecycle not respected.');
        }
        return $version;
    }

}
				

Our next step will be creating the file that contains the version number for us. So create the file src/main/resources/myapp/version.txt that contains only a property hint:

${version}

The last step will be activating the filtering for this file. Let us edit the pom.xml and activate the filtering.

<project>
  ...
  <build>
    ...
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
      </resource>
    </resources>
    ...
  </build>
  ...
</project>
				

Thats it. Now invoke the compilation and have a look at the target directory. For more details on resource filtering haven a look at the maven manual.

[ Previous | TOC | Next ]