In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I’m going to look at how to go about creating and working with components.

In my last article, I posted a list of questions to consider when decomposing the design of an app, and I put together the first cut of the components that will make up my sentiment analysis app. Now it’s time to get into creating the app’s first component, using phix.

Dev Environment Prep

If you haven’t already, you’ll need to install phix onto your dev computer. You’ll find the latest instructions on how to install phix on the Phix Project’s website. Thankfully, we only have to do that once. Now, with the development environment prepared, we can get our component under way.

Creating The Skeleton For The Component

Creating a skeleton component is as easy as:

stuart:~/Devel/sental$ mkdir repustateApi
stuart:~/Devel/sental$ cd repustateApi
stuart:~/Devel/sental$ git init .
Initialized empty Git repository in /home/stuart/Devel/sental/repustateApi/.git
stuart:~/Devel/sental/repustateApi$ phix php-library:init .
Initialised empty php-library component in .

What have we created?

A Quick Tour Of The Skeleton

Here’s a quick list of what the php-library:init command has created in the repustateApi folder:

stuart:~/Devel/sental/repustateApi$ git status
# On branch master
# Initial commit
# Untracked files:
#   (use "git add ..." to include in what will be committed)
#	.gitignore
#	.hgignore
#	build.xml
#	package.xml
#	src/
nothing added to commit but untracked files present (use "git add" to track)

Each of the files serves a useful purpose:

  • .gitignore and .hgignore

    These are basic filters to tell Git and Mercurial what to ignore in here. As we develop the component, there will be a few temporary folders created which we’ll never want to end up in version control. Filter files for other version control systems are welcome.

  • LICENSE.txt

    Every component needs to come with a clear statement about the rules for re-use, even if it just says All rights reserved.

    If you’re looking to open-source your code, you’ll find many well-tested licenses from the Open Source Initiative’s website.


    Every component needs basic documentation to help a new user get started with it. By putting that into a file, GitHub will automatically pick that up and display it on the component’s website.


    This is a file we’re going to edit shortly. It contains a little bit of metadata about your component, such as it’s name and version number.

  • build.xml

    This is a file for phing, a sort-of Ant clone written in PHP. We’re going to use the commands defined in this file to run our unit tests, build our PEAR-compatible package, and even install it for local testing.

  • package.xml

    This is the manifest file that the PEAR installer looks for when trying to install your component.

    We’re going to edit this file shortly, adding in some data about our component, but most importantly, listing all of the components that our component depends on. Don’t let the terse PEAR documentation put you off; it’s quite an easy file to work with, and the error-prone bits get auto-generated for you by the build.xml file when the time comes.

  • src/ folder

    Here’s where your source code goes. There’s a subfolder under here for each of the different types of file that your component might contain. Don’t worry about that too much for now; we’ll explain what goes where as we build these components up.

Why A Skeleton Helps

Our skeleton takes care of all of the chores and housekeeping for you, leaving you free to focus on writing your code and your tests. It gives you a standard structure to work within, making it very easy to move from one component to the next, or share development duties with a wider (and possibly remote) team.

This structure has been carefully designed to work with the somewhat fickle PEAR installer’s preconceptions, and also to work well with both PHPUnit and Netbeans. It should work well with Eclipse/PDT too; let me know how you get on. And old skool vim users shouldn’t have any troubles either :)

As the skeleton improves (pull requests are very welcome!), you can use the very handy phix php-library:upgrade command to get the improvements dropped right into your components. Another bonus feature of adopting a standardised skeleton instead of rolling everything by hand.

In the next blog post, we’ll get and package.xml setup, and get the vendor/ folder created. What’s the vendor folder? I’ll tell you next time :)


  1. Christian Weiske says:
    March 24th, 2011 at 8:31 am

    You should really use a meta package to track and install your dependencies with a single command:

  2. Stuart Herbert says:
    March 24th, 2011 at 9:36 am

    @cw: that would work if users did not need to manually channel-discover.

  3. Manuel Pichler says:
    March 24th, 2011 at 6:38 pm


    ~ $ pear config-set auto_discover 1

    is your friend…

  4. Manuel Pichler says:
    March 24th, 2011 at 6:40 pm

    @sh by the way, PHP_Depend and PHPMD are already stable, so you can omit the “-beta” and “-alpha” suffix :)

  5. Stuart Herbert says:
    March 24th, 2011 at 8:49 pm

    Ah ha! That will save a lot of effort :) And Sebastian will be able to simplify his install instructions for PHPUnit too … :)

  6. Brett Bieber says:
    March 25th, 2011 at 12:59 am

    Just FYI, the PEAR2_Pyrus_Developer tools have a skeleton generator built in.

    php pyrus.phar generate-pear2 MyPackage

    Docs here:

    Pyrus also prompts for undiscovered pear channels if they aren’t already discovered.

  7. Stuart Herbert says:
    March 25th, 2011 at 3:02 pm

    @Brett: Thanks for the tip about Pyrus. Unfortunately, its skeleton is both too-PEAR project and too-Subversion specific for me to recommend to anyone today. Pyrus hasn’t yet been picked up by Linux distros, which sadly is a reason I can’t recommend it in this series of blog posts. Perhaps one for the future?

  8. Brett Bieber says:
    March 25th, 2011 at 5:14 pm

    @Stuart: The subversion layout has been removed, as all of the PEAR2 development is now in github. The docs are a bit outdated I suppose, but it has been around for quite a while. Yes it is PEAR package specific, and also can generate PECL package skeletons.

    Pyrus doesn’t require any complex installation, so I doubt it would be distributed by distros. It’s self-contained in a .phar and can be used right out of the box.

  9. Stuart Herbert says:
    March 25th, 2011 at 9:51 pm

    @Brett: would be great to see the docs brought up to date. As long as distros ship the old PEAR installer and not Pyrus, you’re going to find adoption rates for Pyrus lower than one would like. It needs addressing :)

  10. Stuart Herbert says:
    March 26th, 2011 at 1:11 pm

    @manuel: I have now tested PEAR’s auto_discover setting. It doesn’t work :(