In my last post, I discussed do’s and don’ts for making a PHP application portable. This week, I will show you how to create a preflight checker in the CodeIgniter PHP framework to ensure that an environment will support your application.

Note: This article assumes that you already have a working CodeIgniter application setup.  If you are interested in getting started with CodeIgniter, there are some really great tutorials on the web.  If you’re not using CodeIgniter, skip to the “What to Check” section below for a general idea of how to apply this to PHP apps in general.

Setting up the Hook

The best way to setup a preflight checker is to create a hook.  Make sure that you enable hooks in your main configuration file before getting started.  We’ll be setting up a pre-system hook, so add the following code to your application/config/hooks.php file:

/*Preflight Check Hook*/
$hook['pre_system'] = array('class' => '',
'function' => 'preflight_check',
'filename' => 'preflight_check_hook.php',
'filepath' => 'hooks');

This will tell CodeIgniter to run this hook every time the system starts.  As you can infer from the above code, we’ll now have to create a file in the application/hooks/ folder (if it doesn’t exist, create it) named preflight_check_hook.php and add a function to that file named preflight_check():

/**
 * Preflight Check checks all of the prerequistes before the first
 * pageview for each session.
 *
 * If a problem is found, the program halts execution.
 */
function preflight_check()
{
  //all your checks go here
}

Now we’re ready to add checks so we can test the server environment.

What to Check

Technically, you can check whatever you want here, but I tend to check the things that are likely to be different from one server environment to the next.  Some of the more important ones are:

• Whether the version of PHP or CodeIgniter is new enough to support your application.  You can check this by using the phpversion() function
• Necessary PHP Extensions installed?  You can check this by using the function_exists() function.
• PHP.INI variables set correctly?  You can check this by using the ini_get() function.
• Whether certain folders are really writable on the server or not
• Whether files exist or not.

Of course, you can check for most anything you want to in the preflight check, and even try to tweak the environment a little using ini_set().  What you can’t do is access most of the functionality in CodeIgniter, since this hook will run before most of your libraries are loaded.  There are a few useful CodeIgniter variables and functions that you will have access to, though:

• show_error() — For printing out errors (non CodeIgniter users should use the die() function)
• is_really_writable() — For testing if a file is writable or not (non CodeIgniter users should use the is_readable() function)
• $application_folder and $system_folder

Rather than bore you with lengthy explanations of each type of check, it will be easier to simply show you an example of how I typically do it.  Below is an example preflight check hook that I ripped almost verbatim from one of my applications:

function preflight_check()
{
	global $application_folder;
	global $system_folder;
 
	//Ensure proper version of PHP
	if (phpversion() < '5.1')
	  show_error("This application requires at least PHP 5.1 to run properly!");
 
	//Ensure SQLITE extension is installed
	if ( ! function_exists('mysql_connect'))
	  show_error("The sqlite PHP extension is required to run this application!  Refer to <a href="http://us.php.net/manual/en/book.sqlite.php">the PHP documentation for this extension</a> for more information.");
 
	//Ensure GD2 is is installed
	if ( ! function_exists("gd_info"))
		show_error("The PHP GD2 image library is required to run this software.  Check with your server administrator or hosting provider, or <a title="Installation Instructions for GD2>refer to the PHP documentation for installation instructions</a>.&quot;); 	//Check if the system cache directory is writable 	if ( ! is_really_writable($system_folder . " href="http://us2.php.net/manual/en/intro.image.php"></a><a title="JSON extension installation instructions" href="http://us3.php.net/manual/en/book.json.php">manually install it</a>.)");
 
	//Check memory limit and attempt to set it to what this application needs
	if (get_bytes(ini_get('php_value memory_limit')) < 33554432)
	{
		if( ! ini_set('php_value_memory_limit', '32m')
			show_error("The memory limit in your PHP.INI file must be set to at least 32 megabytes (32m).");
	}
}

You can copy this code into your application/hooks/preflight_check_hook.php and try it out.  Basically, it will halt execution (via the show_error() function) and show an error on the screen that alerts the user to something not being setup correctly if any one of these checks fails.

What’s the Advantage over just letting the program fail on its own?

Technically, nothing; your preflight checker will check things that would normally cause your application to fail at some point in the execution anyway.  This is simply a way for you to alert your admins/developers/users that they need to fix their environment right off the bat.  Plus it’s more graceful and clean than PHP error messages.

Practically, however, this may save a lot of headaches, especially if you distribute the application or expect people to download a copy onto their own desktops for development.  Oh, and if your users/developers/admins have PHP error reporting turned off on their system, then a carefully coded preflight checker will save them from getting a mysterious blank screen when the environment doesn’t match the requirements.

Keeping this thing from running for every page view

You probably won’t want this script to run every time a  page is loaded on your site, especially if the script includes file operations, lest your server take a performance hit.  Typically, you will want to run this preflight checker only once per session.  By adding a few lines of code to the top and bottom of this function, you can make it run only once per session (unless it fails).

function preflight_check()
{
	//See if this has already been run during the current session
	session_start();
	if (isset($_SESSION['preflight_check_pass']) && $_SESSION['preflight_check_pass'] == 'pass')
		return TRUE;
 
	global $application_folder;
	global $system_folder;
 
	//Ensure proper version of PHP
	if (phpversion() < '5.1')
	  show_error("This application requires at least PHP 5.1 to run properly!");
 
	// All of the
	// rest of your checks
	// go in here...
 
	// ...
 
	//Woo hoo.. the check passed!
	$_SESSION['preflight_check_pass'] = 'pass';
}

You’ll notice that this example uses PHP’s built-in session system rather than CodeIgniter’s session library.  This is because CodeIgniter’s will not have been loaded yet when this hook runs, and because we’re not storing any particularly sensitive information in this session, so we don’t have to take advantage of CI’s advanced session security features.

Well, that’s about it for now.  If you have any comments or see any issues with the examples in today’s post, feel free to share by leaving a comment.

“Portable” means that your application is able to run on any PHP webserver with minimal fuss.

Ensuring portability is an absolute must for programs that are packaged and distributed for public consumption, like WordPress or MediaWiki.  But, you should aim for portability in all of your applications.  The ideal is a one or two-step installation process and only two or three system requirements:  1. Webserver (IIS/Apache/etc), 2. PHP v5.X+, 3. MySQL 4+.

Why Make it Portable?

For one, it keeps things simple.  The concept of portability meshes well with the KISS concept that I value so highly.

Secondly, it makes deploying your application to a new server simple if the need ever arises.

Thirdly, it enables you to easily distribute your package to the world if that is your intention.  I, for one, simply hate installing web applications on my server with long lists of prerequisites and a lengthy install process, especially if one of those steps is to install another set of libraries (e.g. from PEAR) before installing the application itself.

Finally, portability makes distributed development easier.  Many applications are developed on Windows but run on Linux.  Portable applications eliminate the headaches involved in trying to get the to two environments (development & production) to match.

How to Make Your Application Portable

A truly portable application will work out-of-the-box, and require minimal configuration.  It will also automatically check the environment for specific configuration or prerequisites that do happen to be required.  Below are five things to try and avoid, and one thing to try and do to ensure your application is portable:

1. Don’t rely on exotic PHP extensions

I’m talking about extensions that are not bundled with PHP or found pre-installed on most hosting providers.  If you do require a specific PHP extension that is not bundled with PHP, you should check for the existence of the extension at the beginning of the program’s execution.

For example, many of my applications require JSON libraries, which some versions of PHP5 do not include, so I check for the existence of the json_encode function when the application first runs.

2. Don’t rely on separate installation of PEAR Libraries

Don’t get me wrong; PEAR is great.  But, you shouldn’t predicate the successful execution of your application on your users installing external libraries.  Most PEAR libraries are dependent on other PEAR libraries, and require the user to figure out and install multiple packages.  Your application should not require this pre-setup, and it should run with all of the required libraries and classes included.

3. Don’t rely on command-line configuration

If you want your application to be truly portable, you have to cater to the crowd who has only FTP access to their servers.  Yes, these folks are few-and-far-between, but coding with them in mind ensures that your application setup procedure is as simple as possible.  This means that your installation instructions should be completely void of anything that says “login to the command line and run xyz command”.

Definitely don’t rely on the user to have administrative privileges on the server.  This means to try to avoide the necessity for external software or packages (although this is unavoidable sometimes).

4. Don’t rely on the program to be run on a specific operating system

This one is  a stretch for some people, but truly portable applications can run on Windows, Linux, or MAC servers without fuss.  I make all my applications portable enough to run on any OS simply because we use SVN for development, which requires my developers to download fully working copies of the project to their desktops.  Since my developers use Windows & Mac, and my servers run Linux, my applications have to be cross-platform compatible.

5. Don’t rely on PHP.INI customizations

A lot of PHP applications I have tried won’t work with magic quotes (or vice versa), or won’t work without the user increasing the amount of memory or upload file size for PHP.   Before making these nice-to-have’s required, ask yourself if you can find a different way to solve the problem.

For situations where it is unavoidable to ensure that a specific directive is set, your application should automatically attempt to override the default PHP.INI customization via ini_set() and then inform the user in plain English that the ini value needs to be changed.

6. Do include a mechanism in the application to test for required prerequisites at the very start of execution (or as part of the installation process)

Rather than have your application spit out a generic PHP error message when it comes across an environment setting that it doesn’t like, you should include a function that performs a “pre-flight checklist” at the beginning of runtime for each session, or at least the very first time your application is run.

Next week, I will show you how to do exactly this by creating a hook in CodeIgniter that thoroughly tests the environment, and informs the user how to remedy issues.

For Further Reading, I recommend:

• Writing Portable PHP Code from PHPwact.org
• Making Your PHP Code Portable from mtdev.com