PhpRiot
News Archive
PhpRiot Newsletter
Your Email Address:

More information

Setting Up Your Component's Metadata, Pt 1

Note: This article was originally published at Planet PHP on 25 March 2011.
Planet PHP

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 the last post, I used phix and ComponentManager to create an empty component. I now need to edit the component's manifest files before I can start cutting code.

What's Your Component Called?

The first file we need to edit is called build.properties. It's a standard-format .ini file that contains a few bits of data for us to edit. When I designed the component skeleton, I put these in their own file so that we never have to edit the build.xml file a which means we can upgrade build.xml in future via the phix php-library:upgrade command.

An unedited build.properties file looks like this:

project.name= project.majorVersion=X project.minorVersion=Y project.patchLevel=Z checkstyle.standard=Zend component.type=php-library component.version=3

As this is the first version of my component, I'm going to call this version of the component repustateApi-0.1.0. That means that I need to change the top four lines of build.properties to look like this:

project.name=repustateApi project.majorVersion=0 project.minorVersion=1 project.patchLevel=0

(You can see the fullly-edited build.properties file on GitHub).

Why did I pick 0.1.0 as the version number?

What's In A Version Number?

When it comes to components, we need to adopt a sane and engineering-focused version numbering scheme, otherwise we run into a lot of trouble when trying to trust our own and other people's components over time. I went into this in some detail in my Beyond Frameworks talk, and it basically boils down to this:

  • The scheme itself reads major.minor.patchLevel, or, if you prefer, x.y.z.
  • All versions 1.y.z must be 100% backwards-compatible. You can fix bugs and add new features, but if you break backwards-compatibility, you need to create version 2.y.z.

    The people who use your components need to be confident that they can upgrade the component (to get the latest fixes and features) without any nasty surprises that force them to also go to the trouble of editing their own code. Make the major version number your promise to other developers that they can upgrade safely.

    Don't be afraid to create version 2.y.z, version 3.y.z etc as rapidly as needed. Google has done exactly this with Chrome, and it hasn't exactly done them any harm.

  • If you're adding new features, and not breaking backwards compatibility, turn version 1.0 into version 1.1, 1.2, and so on.
  • And if you're only putting out bug fixes, just increase the last number, and turn version 1.0.0 into version 1.0.1, 1.0.2 and so on.

This numbering scheme is called Semantic Versioning. Please do follow it.

That's all that we need to edit in build.properties. We still need to setup package.xml, which I'll cover in the next blog post.