PhpRiot
News Archive
PhpRiot Newsletter
Your Email Address:

More information

PHP Components: Explaining File Roles

Note: This article was originally published at Planet PHP on 4 April 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 previous articles, I've introduced you to the component skeleton that ComponentManager creates for you when you run the phix php-library:init command. Our skeleton is designed to be extremely clean, so that it is very easy to automatically generate your PEAR-compatible component and its package.xml file, so that you don't have to maintain it yourself (a process which would only end in tears).

At the heart of our skeleton, are the design constraints imposed by the PEAR installer, and that means the way it handles files differently depending on the file's role.

What Are File Roles?

A file's role is simply a way of telling the PEAR installer where you want the file installed. The PEAR installer supports the following file roles:

  • data - any data files that your component needs to read at run-time
  • doc - documentation about your component
  • php - your PHP code
  • script - any command-line scripts your component includes
  • test - your (hopefully, PHPUnit-based) tests
  • www - PHP code to be served by Apache

a plus a few more that are of no interest to authors of PHP components.

Where Do I Put Files For Each Role?

To make it extremely easy for the phing pear-package command to auto-generate your package.xml file, there's a folder in our component skeleton for each type of file.

Here's a handy summary showing you where to put your files inside your component, based on their role:

  • data - goes in the src/data/ folder
  • doc - goes in the src/doc/ folder
  • php - goes in the src/php/ folder
  • script - goes in the src/bin/ folder
  • test - goes in the src/tests/unit-tests/ folder
  • www - goes in the src/www/ folder

In the next few articles, I'm going to look at each of these file roles in turn, and show you in detail how the PEAR installer treats them, and how to work with them in your own components, starting with the php role.