PhpRiot
News Archive
PhpRiot Newsletter
Your Email Address:

More information

PHP Components: Shipping Data Files With Your Components

Note: This article was originally published at Planet PHP on 20 April 6760.
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.

I'm now going under the bonnet of our components, and looking at the different file roles that the PEAR installer expects to find when we distribute our component as a PEAR-compatible package. Although the vast majority of your components will simply be libraries of code, sometimes you might need to ship data files for them to operate on. Thanks to the PEAR installer's data role, this is possible.

What Is A Data File?

A data file (the adata' file role supported by the PEAR installer) is an arbitrary file that your code either reads from, or (in the case of images et al) serves up to other programs.

There are some important practices and limitations that you need to follow to avoid any disappointments or nasty surprises:

  • Data files should not be PHP code that you plan on executing.

    Your users expect your code to be in the standard place (which is /usr/share/php for popular Linux systems, or vendor/php/ in the per-app sandbox). Follow the rule of no surprises, and make sure you put your code where your users expect to look for it.

    For example, PEAR's HTTP2_Request component ships PHP code in its data folder, code to rebuild the Public Suffix List (which is, itself, a data file). The chances are that most of HTTP2_Request's users are unaware that the data folder exists, and that there is code in the data folder which they might need to use. Another example is ezComponent's ConsoleTools, which ships a UML diagram for ezComponents in its data folder. This probably belongs in the docs folder, if it is meant to be read by developers using ConsoleTools. My local /usr/share/php/ contains many more relevant examples; yours' probably does too.

    Our component skeleton offers an alternative approach, to ship generate-list.php a properly-installed command-line program, or perhaps as a drop-in command for phix.

  • Data files cannot be written to; your code should treat them as read-only.

    When your data files are installed for system-wide use, the files are owned by the root user. Unless there is an almighty security cock-up, your code will never ever actually get to run with the root user's security privileges. If your code tries to write to these data files, it will generate a runtime error.

    But this won't show up when you unit-test your code. So remember, and don't write the code in the first place

Where Do Data Files Go Inside The Component's Structure?

If we take a look at the ComponentManagerPhpLibrary component, you'll find the data files are inside in the src/data/ folder. These are the skeleton files used for a PHP library component.

src/data/ is meant to be a folder that holds the data files that you want installed into the computer system.

Where Do Data Files Get Installed?

When you use the PEAR installer to install your component:

$ pear install Gradwell/ComponentManagerPhpLibrary

all of the files in your component's src/data/ folder gets installed into /usr/share/php/data/ on your computer:

The PEAR installer's behaviour here is different to both command-line scripts and PHP code; the installer crea

Truncated by Planet PHP, read more at the original (another 2872 bytes)