boot

First steps with PHP - booting a script, Part 2

developer — Fri, 25 Apr 2008 22:22:13 +0000

If you haven't already, you may want to start with Part 1 of this topic. Part 2 of my discussion on booting begins with a digression.

Frameworks and libraries

Some time ago, I read an article by Rasmus Lerdorf titled The no-framework PHP MVC framework. It got me thinking about my framework, which at the time I was converting from PHP4 to PHP5.

In the good old days, if you wanted to create re-usable code, you would create a library of related functions or objects. Now, the excitement is all around frameworks. Everyone has one. What is the difference between the two?

In my mind, a library:

Is under the control of the application
Provides a set of functions or objects for performing a closely related set of tasks
Has few pre-requisites
Works independently of other libraries

A framework:

Controls the application
Tends to enforce a methodology
Performs a wide range of tasks
Contains code that is heavily dependent on the framework environment. It would be difficult to extract a single piece of functionality without dragging in most of the rest of the framework.

I like the synergy of the framework, but I also like the flexibility and lighter weight of a library. Frameworks tend to be biased to solving a specific kind of problem. I wanted something more general.

My framework would:

Be object-oriented
Be under the application's control
Provide an architecture that allowed addressing a wide range of tasks
Consist of "libraries" which worked synergistically but which would also allow integration of external functionality (through base classes and interfaces)
Minimize the amount of core classes needed to use the framework

I know that calling my framework a "framework" creates some confusion. It is not a framework like CakePHP but it is a framework like the Java framework. Until a better term comes along, I'll stick with it.

Back to booting

Let's return to our main topic. The digression was necessary because it led me to completely separate the boot and framework code. Each operates independently from the other.

Returning to where we left off last week, we know that each Web page begins with

require 'include.inc';

where include.inc contains:

$fileTop = ...;
require "$fileTop/res/boot/boot.inc";

The boot.inc performs certain tasks but never directly accesses the framework code. The framework, in return, never directly uses any of the variables or functions defined in boot.inc.

Directory structure

This is the directory structure I use:

Notes:

The "res" directory contains all resources except images. This includes CSS, Javascript and PHP code.
The "boot" directory contains just one file, boot.inc. I just the same boot.inc file to boot many sites.
The "site" directory contains all the site-specific files. The boot system requires two files in res/site/php: conf.inc and setup.inc.
The "th" directory contains the Tiger Heron framework which I will cover in future articles.

The boot sequence

I can finally describe the boot sequence:

The server loads the Web page
The Web page loads include.inc
In include.inc, define $fileTop and load res/boot/boot.inc
In boot.inc, load res/site/php/conf.inc
Define some variables, set the include path and perform some basic initialization
Finish boot.inc by loading res/site/php/setup.inc

The conf.inc file gives the site a "hook" for any special setup that must be performed immediately. It also allows the site to configure some site-specific values for boot.inc. Code in conf.inc is limited by the fact that the include path has not been set up. It also cannot rely on any functionality other than what is in boot.inc and what is bundled with PHP.

While conf.inc is customized for each site, I usually start with a template. The template indicates some values I may want to define and speeds up construction of new Web sites.

Boot.inc will:

Define $webTop, the relative path to the top of the site. This is usually, but not always, the same as $fileTop. I use $fileTop to reference files in the file system and $webTop to reference files through the Web server (e.g. CSS files, Javascript files, etc.).
I determine whether this site is running on my PC, on a staging site or on a production site.
The error reporting is set based on where the code is running. On production sites, all error reporting is suppressed, while PC and staging sites report all errors.
I set up the include path based on the system type and values passed in by conf.inc.
I turn off user aborts, as these can wreck a database.
I remove magic quotes if they have been applied.
I allow for Macintosh line endings.
I set the content type to either text/html or application/xhtml+xml depending on whether I am using XHTML (a conf.inc option) and whether the browser supports application/xhtml+xml.
I use UTC as the timezone.
I define some absolute and relative paths to various commonly accessed places.

Having completed this list of tasks, res/sites/setup.inc is called to finish off any site-specific setup. It is the setup.inc file that determines whether the framework code will or will not be included.

I've left off one important step. The Web page, before including any code, can set define some values of its own. Let's say, for example, that you wanted to enable caching for some files and not others. The conf.inc file could include the default choice and each Web page could override that choice.

To make this clear, the Web page would start with:

$useCache = false;
require 'include.inc';

And the conf.inc file would contain:

if (!isset($useCache)) $useCache = true;

Finally, the setup.inc file would set up the caching based on the value of $useCache.

The caching example points out that boot.inc doesn't include all the tasks you may need for some Web sites. For instance, there is nothing in boot.inc for handling caching and sessions. These are more complicated tasks and are supported by the framework. Since the boot sequence can't depend on the framework, these additional tasks are left to setup.inc. For rapid site building, I have a template for setup.inc, but I am free to change it as appropriate for the site.

The .htaccess file

One of my goals was to be able to copy the entire site from my PC to the staging or production servers without requiring any code changes. Sometimes, code in the .htaccess file cannot be written to be system independent.

I used to have to maintain two copies of the .htaccess file, one for my PC and one for the hosting site. It occurred to me one day that I could start up my PC's Apache server with a -D DEVELOPMENT_ENV command-line option. This allows me to separate PC and hosting options using

<IfDefine DEVELOPMENT_ENV>
  ...
</IfDefine>

and

<IfDefine !DEVELOPMENT_ENV>
  ...
</IfDefine>

Mission accomplished

If you go back to Part 1 of this topic, you'll see I have met all the goals I set for myself without violating any of the restrictions I listed.

The boot sequence is fast, performing only what I need to support my PC/staging/production development approach. It also initializes the PHP environment, since I can't count on being able to set php.ini or using php_flag and php_value in my .htaccess file.

The boot sequence provides two hooks for site customization. I can also choose to use it with or without my framework. This gives me a lot of flexibility.

If you want a closer look at this, I have packaged up the boot code for a site at www.sample.com. The package includes two Web pages, index.php and subdir/index.php with the supporting boot files. It does not include any framework code.

First steps with PHP - booting a script, Part 1

developer — Tue, 18 Mar 2008 23:57:56 +0000

Having covered downloading and installing PHP and setting up a development environment, I'm now actually going to talk about writing PHP code! Specifically, I will describe how I boot my PHP scripts and why I boot them the way I do. Part 1 shows how my requirements for code portability and maintainability influence the boot process. Part 2 will go into more detail about the specific steps executed by the boot code.

My environment

Here's some background: I develop sites for multiple clients. Initial coding occurs on my Windows XP system. When the code is running well, I upload it to the client's hosting system, which is typically Linux based.

I start by creating a new directory for my client's Web files (on my PC) and then creating an alias in my Apache configuration file to point to this location. For this article, let's assume I reach the Web site using http://localhost/sample.

A sample task

For our first PHP class, let's tackle something easy—let's use PHP code to generate our sample site's navigation menu. Here's a quick sketch of the navigation class:

<?php
class Navigation
{
    public function printMainNav()
    {
        echo '<ul><li><a href="index.php">Home</a></li>....';
    }
}
?>

and here is the index.php page using the class:

<?php require 'Navigation.inc'; ?>
<html>
  <head>
    ...
  </head>
  <body>
    <?php $navigation = new Navigation(); $navigation->printMainNav(); ?>
      ...
  </body>
</html>

At this point, the directory we created contains two files:

index.php
Navigation.inc

The code works, but we're already seeing some potential pitfalls. First, we don't want to place the PHP classes in the same directory as the Web pages. Secondly, our sample system will eventually grow to where we will use sub-directories to organize our Web pages. The problems we see are:

Each Web page will need to include the Navigation.inc file based on the Web file's location. If we ever change our mind about where to place Navigation.inc, a lot of files will need changes.
The link to the home page (in the navigation), as written, only works for Web pages at the top of the directory tree.

It may seem that there are some easy work-arounds for these two problems. For instance, setting the path to the Navigation.inc file in the php.ini file solves the first problem. And linking to "/sample/index.php", solves the second. The reason these solutions aren't ideal lies with the environment in which I work.

Goals and requirements

These are my goals:

I want to use a consistent approach for all my clients.
I want to allow for sub-directories in the Web site.
I want all Web files to have a consistent way of including PHP code, regardless of their location on the site. This lets me use the same template for all files and to move a file from one place to another without having to edit it.
I don't want the Web pages to use any complicated calculations in order to include PHP code. Complicated code should be stored in one place, not scattered in every Web page.
I want to be able to upload the code from my Windows system to the hosting system without any changes and have it work in both environments.
Occasionally, I also want the code to work without change on a testing site on the hosting system. This lets the client preview site changes without affecting the site the customers sees.

These are the restrictions I have:

I can't alter the php.ini file since shared hosting services usually don't provide access to this file.
I can't place php_flag or php_value statements in the .htaccess file. These only work if PHP is run as an Apache module and some hosting companies use Fast CGI. (Note: apparently, this limitation will disappear in PHP 5.3.)
I can't assume I can reference a Web page at the top of the site by starting the path with "/". This might work for the final site, but not for the site on the PC, where the top is at /sample.

My current solution

I have not found the perfect solution. What I use is pretty close:

Each Web page begins with <?php require 'include.inc'; ?>.
Each Web site directory contains an include.inc file with the following contents:
```
<?php
  $fileTop = '.';
  require "$fileTop/res/boot/boot.inc";
?>
```

The advantages are:

We can move Web files from one directory to any other without editing.
The variable $fileTop identifies the file path to the top of the root of the Web site.
$fileTop is a relative path, so the Web site tree can be located anywhere in the site's document root.

It's not a perfect solution because I still have to create one include.inc file per directory. Of course, that's not very many files and the contents are not complicated. Any heavy lifting can be relegated to the boot.inc file.

It's also not perfect because it requires an extra file load for the include.inc file.

It assumes that '.' is in the php.ini search path. So far, this has proven to be a safe assumption.

Alternatives

Drupal and a number of other systems use a common dispatcher page for all Web site accesses. Every page loads index.php, which then includes the desired content. $fileTop is always '.'.

Using Apache's mod_rewrite module, the process could work like this:

The user enters http://www.sample.com/somepage.
Mod_rewrite converts this to http://www.sample.com/index.php?q=somepage.
The index.php file is loaded.
The index.php can directly contain the boot.inc code. This saves one include/require.
It uses the 'q' parameter to determine which page the user really wanted.
That Web page somepage.inc is included.

This eliminates two file includes. There is some hidden cost in that the mod_rewrite script probably has to do a file check to see if the requested Web file actually exists—this allows access to CSS, Javascript and image files that you may not want handled by PHP.

One problem with this approach is that my Web pages can set some options before loading the include.inc file and these options control aspects of the boot process (e.g. whether to use caching, whether to use sessions, etc.). I will discuss this more in Part 2 of this article; we might lose this flexibility in the single dispatcher approach or we might have to work around it in a way that voids the performance gain. Not having tried this alternative, I'm not sure of the answer.

Do you have an even better approach? Please let me know.

More to come

In Part 2, I will discuss what happens when the boot.inc file is executed. Stay tuned!