Publishing PHP libraries using Github, Travis and Composer

While PHP had a package manager for a long time, in the form of PEAR, it never really took off or become ubiquitous. The most common way to install a library has always been manually which is a shame given how practical a package manager can be.

Fortunately, things are changing for the best since Composer. This package manager, inspired by NPM from Node.js, is getting a very good traction and, I think, is slowly becoming the de facto PHP package manager.

In combination with Github and Travis, the trio gives you all the right tools to publish and manage your Open Source PHP library.

I don’t think Github needs any kind of presentation but you may not know Travis. It is an online continuous integration service (based on the Open Source project of the same name). Basically, it runs your test suite for you and sends you a report each time some commits are pushed on Github. You may have noticed the small green badge “build successfull” on some Github projects which indicates that they’re using Travis.

Setting up your project to use these tools is pretty straightforward. First you’ll need to have a good organization in your repository. Messy source codes are harder to dive into and harder to manage. Prefer saving the actual source code of your project in a src or lib folder (your pick, there doesn’t seem to be any real convention) in the root of your repository. Use a coding convention and choose your namespace organization accordingly. Follow the PHP FIG conventions as much as you can, they’re becoming the standard.

Your library should be testable. Writing unit tests can be a hassle but it makes the whole thing much more easier to maintain, easier for other people to contribute and (most of the time) avoids introducing bugs in existing code. The most common unit testing library in PHP is obviously PHPUnit. Save your test cases in a tests folder in the root of your repository. Create your phpunit.xml.dist file. Mines usually look like this:

<?xml version="1.0" encoding="UTF-8"?>

<phpunit backupGlobals="false"
         backupStaticAttributes="false"
         colors="true"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         processIsolation="false"
         stopOnFailure="false"
         syntaxCheck="false"
         bootstrap="tests/bootstrap.php"
>
    <testsuites>
        <testsuite name="Example Test Suite">
            <directory>./tests/</directory>
        </testsuite>
    </testsuites>

    <filter>
        <whitelist>
            <directory>./src/</directory>
        </whitelist>
    </filter>
</phpunit>

Note that I use a tests/bootstrap.php file which is ran before the test suite. It sets up the include path and any dependencies. The library source code is located in src.

Travis needs a travis.yml file at the root of your repository. You’ll find more information here but it is a very simple YAML file, here is an example:

language: php
php: 
  - 5.3
  - 5.4
script: phpunit

If your library has any dependencies managed through Composer, add this line:

before_script: composer install

To enable Travis for your project, signup on their website using Github and choose which projects should be tested.

Before announcing to the world your great new library, don’t forget to provide a LICENSE file containing the full text of your license and a README (or README.md for a markdown formated file). It should at least explain what the project is about, how to install it and the basics of using it. If a README is not enough, consider writing proper documentation (maybe using Beautiful Docs). It’s always a good gesture to provide an example usage of your library. I usually have an example.php file or an example folder for more complex projects.

To add the Travis build status to your README.md, add the following markdown snippet (replace example/example with your project name):

[![Build Status](https://travis-ci.org/example/example.png?branch=master)](http://travis-ci.org/example/example)

To be able to publish your project using Composer, you’ll need to provide a composer.json file. The project has a pretty good documentation. Here is a basic one:

{
    "name": "example/example",
    "description": "One liner description",
    "keywords": ["keyword"],
    "homepage": "https://github.com/example/example",
    "type": "library",
    "license": "MIT",
    "authors": [{
        "name": "John Doe",
        "email": "john@example.com",
        "homepage": "http://example.com"
    }],
    "require": {
        "php": ">=5.3.0"
    },
    "autoload": {
        "psr-0": {"MyLibraryNamespace": "src/"}
    }
}

The project name is in two parts, the first one being the vendor name and the second one the library name. Note the autoload section which specifies that the PSR-0 convention is used as well as the namespace and the source code location.

Signup on Packagist, the main Composer repository. Connect your Github account and activate which projects Packagist should publish. Note that version numbers are tracked using Git tags (git tag 1.2.3 and git push --tags).

You can now patiently wait for your first issue or better, your first pull request ;)



comments powered by Disqus

18/02/2013