I love, love, love getting rid of crap.  Maybe that’s why I like to read Unclutterer, or think that the 100 Things Challenge is such a great idea.  In real-life, I’m a minimalist, but when it comes to programming web apps, I’ve become a digital pack-rat.

I don’t care if my database grows into a giant data-monster, ready to ravage my server’s hard disk and slow queries down to a crawl; I’ll deal with it.  The key here is to not allow any important history of data to get lost.

Why Deleting is Bad

Here’s an example, to get us started:

Let’s say you have a simple online store, and you’re selling important consumer items to important people.  You have a database that keeps track of your customers, your products, and your transactions.  It may look something like this:

So, you’ve been in business for a while, and you have a bunch of customers in the system, quite a few products, and a lengthy transaction history.  Recently, you’ve decided to stop selling your Jell-O Brain Mold and you’re ready to remove it from your online store.  Common sense says that you would go to your database, find the record referring to your product, and delete it.

But wait!  If you do this, then the entire history of transactions linked to those products become orphaned (theproducts_id field will point to a non-existent record).  So, if you want to go back in at a future date to see the history of how many of those items that you sold, you will be in trouble.  You haven’t just deleted the item from your website per se, you’ve actually deleted the record of the item ever existing in the first place.

And, you don’t want to do that.

Flag It!

The useful alternative would be to add a flag to the data, so that instead of deleting the record, you could mark it as inactive.  This way, it wouldn’t appear on your website, but it would still exist in the database for future reference.

Your tables will now look something like:

Now you can tell your application to only show the products with `active` = “TRUE” on your website, but refer to products with `active` = “FALSE” when viewing older transaction histories.

This works pretty well, and if you program your User Interface correctly, your website users should never actually be deleting records; instead they should be marking them inactive so they “go away” but never truly die.

Audit History

Okay, now it gets a bit more complex.  In some cases, you don’t just want to mark a record “active” or “inactive” (that is, give it the ability to have two states), you also want to keep a complete revision history of that record, including what change was made, who made it, and when.  This way you can see what a record looked like at a particular moment in time.

This is not a new concept.  Think about your bank account.  It’s pretty much a bunch of numbers stored in a database somewhere.  Do you think that your checking account balance is simply a single field in a single record stored in a database?  Heck no!  Every single debit and credit is stored as a separate transaction, showing a complete history of changes to the account.

There are many ways to accomplish this, really, and for me to put up a tutorial, would be to reinvent the wheel.  The key is to think about which data you want to have complete histories on, and which data is not expendable.  Design your application around these constraints.

Sometimes you Just Have to Kill It

I wrote an application that contains patient records.  When an administrator clicks “Delete”, the patient doesn’t really go away; all of the information remains in the database.  Sometimes, however, we must delete the record permanently. Usually this is because a patient opts out of the program and requests to be removed from the study.  I use a special word for this kind of delete: Purge.

But, before the record is purged, the user has to click a checkbox, and go through two “Are You Sure?” screens informing him or her that not only will the patient record be deleted, but also the complete history of that record, and all data associated with it.  I try to have the application show the data in question on the screen the user has to click yes to.

…well, that’s enough for now.  Hope you’re thinking about data consistency, so you too can become a digital pack rat.

Like most development n00bs, after I started using version control, I never looked back.  And neither should you.

It required me to change the whole way that my office operated, though.  See, the way that we were doing things before seemed so simple; we just edited files and shouted at each other if we collided in our editing.  As it turns out, this was a bad thing, and there have been better alternatives around way longer than I’ve even been in this business.

But like most crotchety, over-egotistical developer-types it took a while for me to come around.  Here’s a brief history of my flirtations and eventual commitment to version control.

Our Blissful, Youthful Ignorance

This wasn’t really that long ago…

1..2..3... Easy Peasy Japanesey.. and stupid.

We would all work directly on the files directly on our development server.  We would sit down, SSH into the server using our favorite editor and code away, never thinking of change management, reverting back to old versions, or who would be responsible for what.  Conflict resolution seemed easy… if I was editing a file named welcome.php, I would simply shout across the room, “Hey Mike–don’t work on welcome.php right now, or I’ll have to beat you!”.

Our revision control system consisted of me creating and storing weekly backups of the entire database and file system.  If we made a change that killed the system, we’d simply either lose that week’s work or spend hours debugging it.  It was all gloriously simple.

Version Control Puberty — The Angsty Years

One day, I decided to implement Subversion, mainly because other developers were sneering at me and telling me I was a dummy.  And while I didn’t want to be a dummy, the whole thing seemed overly complicated.  Why would I want to increase complication when everything was working so simple?  I also had some fundamental issues with this new version control idea:

• First off, everybody has to have to get their own copy of the entire file set.  Bad!  Doom! Insecure! I have to trust my developers with the codebase? ::Gasp::
• Secondly, what do you mean that developers can’t see their changes on the server immediately upon commit without some hacked hook system?  This means they’ll have to run LAMP on their local boxes, too!  Geez.. now we have to have local dev environment setup procedures, too..
• Finally, SVN requires management of its own.  You know.. backing up, securing access, and generally managing.  More overhead and more complication!

Grudgingly, in order to remove the “dummy” label from my operations, I implemented Subversion.  It was difficult at first to understand how it would fit easily into our procedures, but with some very helpful free online material, we started using it.

And sure, I did have to write procedures for setting up local dev environments AND install a subversion clients AND manage a repository server, but you know what?

All of that stuff was way worth it.

All Grown-up Now

Let me repeat that: whatever frustrations version control causes, they are all worth it.

After being SVN disciples for a while now, our development procedures have matured.  Here’s how we do things:

The way we do things now.. Much better!

I’ve since tried other VCS systems like Mercurial, Git, and Bazaar, but have not found any compelling reason to switch.   Either way, using version control has saved our sorry butts on more than one occasion and has made life easier in about 1,001 ways.

As a bonus, it has also forced us to use better procedures and generate better development documentation, which is amazing, because we’re pretty lazy.  Now if only we could find a tool to better force us to behave when it comes to unit testing…

Well, that’s my story.  If I’ve inspired you to use VCS, hooray!  Here’s a helpful place to get started.  If not, you’re a dummy.

Thanks all who notified me that the GesHi for CodeIgniter download link was serving up a big, ugly 404 page.  I plan on releasing a new version soon, but in the meantime, I’ve fixed the link.

Any questions, comments, or suggestions are always welcome.  Also, if anybody has tried this plugin on CI 1.7.2, let me know how it works.

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