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 # LICENSE.txt # README.md # build.properties # 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.
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 README.md 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.
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.
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 build.properties and package.xml setup, and get the vendor/ folder created. What’s the vendor folder? I’ll tell you next time 🙂