Do what?

There aren’t many PHP applications (or indeed web applications) out there that don’t need to maintain some form of user state between page requests. This functionality is commonly known as sessions, and most web development languages provide a built-in mechanism for managing them, and PHP is no exception. It’s probably safe to assume that most people reading this probably know what sessions are and how they work, but I think it’s worth taking a moment to spell it out.

The basic idea of sessions is to retain data between page requests without exposing that data to the client. The common way to do this is to store an ID in a cookie that gets passed between the browser and the server as part of every request. If cookies are unavailable then the ID can be added to all internal URLs as GET or POST variables. On the server site this ID refers to some sort of data storage, whether it be a file, a row in a database or an item in Memcache. To restore the session the application simply reads the data corresponding to the ID it’s been passed, and when the request ends it writes it back with any changes.

Sessions time out in two ways. The cookie will usually live until the user closes their browser. Most implementations will also clean sessions from the server if they are not used for a period of time.

The issues

The default implementation of sessions in PHP (file-based) is perfectly adequate for most applications. However, as an application scales you will almost certainly need to spread the load across multiple servers which creates issues for session management.

One solution is known as sticky sessions. This is where the load balancer keeps track of which session ID’s are on which server and routes subsequent requests accordingly. This creates a shedload more work for the load balancer and depending on usage patterns can lead to an uneven distribution of load.

Another solution is to store the session data in a shared resource such as a database or Memcache. This can create excessive load on that shared resource since sessions will generally be accessed on every page request. If you’re lucky enough to need to scale beyond the point where a single database server can handle that load then you’re looking at solutions such as sharding the sessions across multiple database servers and things start to look decidedly over-complicated. That’s the problem that the architecture this post describes aims to solve.

Motivation

Last year (mid-late 2007) we were lucky enough to be faced these issues at Freeads Classifieds so I set about finding a solution that would scale without causing further complications. My motivation was simple… I wanted a system that required near-zero maintenance, and a complex session management system was not going to help achieve that.

Analysis

I started with an analysis of how our application was using sessions. I should note that I inherited this site in early 2007. While it was pretty solid it was clear it had evolved rather than being designed and the way it was using sessions reflected this. I should also note that it’s no longer like that!

The main points I emerged with were…

• A session is created whenever a user logs in.
• Most of the time there is very little data stored in the session.
• A lot of the data that’s stored in the session is the same for all users.
• A lot of the data that’s stored in the session is easily (and efficiently) obtained from other places.

It occurred to me that fundamentally the only thing the session actually needs to contain is the user ID. Everything else can be obtained from the database as needed. However, effective scalability requires that database usage is kept to a minimum, and this led me on to consider how user data is utilised while the user is browsing around the site.

As with most sites it has two distinct parts, the public site and the users area.

The public site has few user-specific data requirements.

• We show a small menu on every page when a user is logged in that includes the users name.
• The menu also states how many messages the user has and how many of those are unread.
• Various forms around the site are pre-filled with the users name, email address and phone number.

So that gives us a need for the users name, email address, phone number and message count for the majority of the site.

In the users area practically every page needs to access the database to provide CRUD functionality. The only thing that ties all that together is the user ID, so let’s add that to our list.

I thought for a long time about whether there was any point in caching more in the session when in the users area, but I came to the conclusion that it wasn’t worth it. If the session becomes too large then it has to be stored server-side rather than being passed with each request, and that takes us back to the issues discussed above. If we’d need to resort to storing the data in a database why not just get the data from where it normally lives rather than duplicating it?!

Implementation

So I now had a limited amount of data I wanted to store between page requests, all I had to do was figure out where. It didn’t take long to realise that I could easily put it where PHP would normally put the session ID - a cookie. Note that you could also pass it as a GET or POST variable if required, but Freeads has always required cookies and it’s never been a problem in the past.

Clearly the cookie needs to be encrypted - we don’t want malicious users to be able to change its contents. For this I turned to the Mcrypt extension. I’d used it before for server-side encryption and have found it to be reliable and performant so it ticked all the boxes.

My user implementation is a class, but I only intend to show some extracts. Hopefully it will be clear where stuff like self::LoginTokenKey and self::TokenCookieName are coming from.

public function CreateLoginToken()
{
    $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_256, MCRYPT_MODE_ECB);
    $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
    $token = mcrypt_encrypt(MCRYPT_RIJNDAEL_256, self::LoginTokenKey, serialize($GLOBALS['__USER__']), MCRYPT_MODE_ECB, $iv);
    Cookies::Set(self::TokenCookieName, base64_encode($token));
}

The encrypted value is not limited to printable characters so I base64_encode it before sticking it in the cookie. The global variable is an array containing 4 of the 5 data elements we need to store. The message count is the only part of the set that needs to be re-read on every page request so that’s done via an AJAX request so that database hit doesn’t delay the page; it’s not critical information, so if it doesn’t show it’s not the end of the world.

The second parameter to mcrypt_encrypt is the key. This is what secures the encrypted data and should be a string that’s non-trivial and ideally completely unrelated to your application. No I won’t tell you what we use, but I’m certain you’ll never guess it!

The other side of the equation is the decryption. If the cookie exists this method decrypts the data and stuffs it into the global var.

public function TokenLogin()
{
	$retval = false;
	$c = Cookies::Get(self::TokenCookieName);
	if (strlen($c) > 0)
	{
		$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_256, MCRYPT_MODE_ECB);
		$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
		$userdata = mcrypt_decrypt(MCRYPT_RIJNDAEL_256, self::LoginTokenKey, base64_decode($c), MCRYPT_MODE_ECB, $iv);
		$GLOBALS['__USER__'] = unserialize($userdata);
		if ($GLOBALS['__USER__'])
		{
			$retval = true;
		}
		else
		{
			unset($GLOBALS['__USER__']);
		}
	}
	return $retval;
}

Pretty simple stuff really.

The real world

Ok, so life’s never that simple. In the real implementation I also store the current time in the data and apply a separate timeout when doing a TokenLogin. Actually it’s not that simple either.

I’ve modified it to use two cookies. The first is basically the one shown above but if the user ticks the Remember Me option when logging in I set the expiry for this cookie to one year. This essentially means that if a user logs in, closes their browser and the returns to the site later it will appear as if they’re still logged in. We’ve remembered them.

That’s great but we don’t want a remembered user to have access to certain parts of the site without verifying their password, so there’s a second cookie that’s created when they actually log in. I call it the authenticated cookie and it expires when the browser is closed or when the timeout it contains passes. If the user has been remembered and tries to create or modify ads, edit their profile or read/send messages they are asked for their password.

This functionality is pretty simple to implement so I won’t bother posting the code here. The effect is to minimise the effort required from the user to make use of most of the site while still protecting the sensitive areas.

Summary

Personally I don’t think there’s anything ground-breaking here, it’s simply a case of thinking more carefully about how you use sessions and in particular whether you actually need to store that huge array between requests. In my experience traditional sessions can get very large very quickly which tends to slow everything down, especially when you start using a shared resource to store that data between requests.

This implementation (or rather a few iterations beyond it) has been running on Freeads Classifieds since March 2008 and we’re yet to have any problems with it. Database utilisation is way down and the user experience is a lot slicker. All things considered I’m pretty happy with the way it works.

As always comments are appreciated. If anyone can see any holes in this or can think of ways to improve it I’d love to hear from you.

The default data store for PHP sessions is files, and that’s fine so long as you only have one server, or you can tie each user to one server. When your app scales to the point where each request from a given user could go to one of any number of servers you need to replace this storage mechanism with something accessible from all of them. A database is the obvious choice.

I wrote the code below to solve this problem for a site that get > 1 million unique users per month (at the time of writing). It’s designed for ease of use and maximum performance. The session table exists in its own database so it can be moved to a dedicated server if required. It would also be trivial to split the session data across several tables by hashing or modifying the session ID to indicate which shard it was on.

The code is liberally commented so I won’t waste electrons describing it separately. Hopefully the way it works is straightforward and easy to understand. Don’t forget to check out the session documentation on the PHP website for full details about putting in your own session handler.

/***********************************************************************
	MySQL Session class

	This class encapsulates everything needed to store your PHP sessions
	in a MySQL database. To use it simply call Session::Start() instead
	of session_start().

	You'll need a table like this in your database. You can change the
	name but the fields should remain as they are defined here.

	CREATE TABLE `sessions` (
	  `id` varchar(50) NOT NULL,
	  `name` varchar(50) NOT NULL,
	  `expires` int(10) unsigned NOT NULL default '0',
	  `data` text,
	  PRIMARY KEY  (`id`, `name`)
	) TYPE=InnoDB;
***********************************************************************/
class Session
{
	private $lifetime = 900;
	private $db = false;
	private $table = 'sessions';
	private $name = 'phpsess';

	static public function Start($host = 'localhost', $username = 'root', $password = '', $db = 'sessionstore', $table = 'sessions', $lifetime = 0)
	{
		// Create the object
		$GLOBALS['_SESSION_OBJ_'] = new self($host, $username, $password, $db, $table, $lifetime);
		// Hook up the handler
		session_set_save_handler(
						array(&$GLOBALS['_SESSION_OBJ_'], 'Open'),
						array(&$GLOBALS['_SESSION_OBJ_'], 'Close'),
						array(&$GLOBALS['_SESSION_OBJ_'], 'Read'),
						array(&$GLOBALS['_SESSION_OBJ_'], 'Write'),
						array(&$GLOBALS['_SESSION_OBJ_'], 'Destroy'),
						array(&$GLOBALS['_SESSION_OBJ_'], 'GC')
					);
		// Start the session
		session_start();
	}

	private function __construct($host = 'localhost', $username = 'root', $password = '', $db = 'sessionstore', $table = 'sessions', $lifetime = 0)
	{
		// By default we use the session lifetime in php.ini, but this can be overridden in code
		$this->lifetime = ($lifetime == 0 ? get_cfg_var('session.gc_maxlifetime') : $lifetime);
		// This is the table where session data is to be stored
		$this->table = $table;
		// Now we connect to the database, throwing expections if anything fails
		$this->db = @mysql_connect($host, $username, $password);
		if ($this->db === false)
			throw new Exception('Failed to connect to the session store', 1);
		if (false === @mysql_select_db($db, $this->db))
			throw new Exception('Failed to select session store', 2);
	}

	public function Open($path, $name)
	{
		// Store the session name for future use, we don't have any use for the path
		$this->name = $name;
		// Everything is OK if we have a connection to the database
		return ($this->db !== false);
	}

	public function Close()
	{
		// Run the garbage collector 10% of the time
		if (rand(1, 10) == 5) $this->GC($this->lifetime);
		// Close the database connection
		return @mysql_close($this->db);
	}

	public function & Read($id)
	{
		// By default we return nothing
		$retval = '';

		// Try to read an entry from the database
		$result = mysql_query('select data from `'.$this->table.'` where id = "'.mysql_real_escape_string($id, $this->db).'" and name = "'.mysql_real_escape_string($this->name, $this->db).'" and expires > '.time().' order by expires desc', $this->db);
		if ($result !== false and mysql_num_rows($result) > 0)
		{
			// Found one, get it
			$result = mysql_result($result, 0, 0);
		}
		@mysql_free_result($result);

		return $result;
	}

	public function Write($id, $data)
	{
		$retval = false;
		// Build the query. We use the MySQL ON DUPLICATE KEY feature to do an insert/update in one query.
		$sql = 'insert into `'.$this->table.'` set ';
		$sql.= 'id = "'.mysql_real_escape_string($id, $this->db).'", ';
		$sql.= 'name = "'.mysql_real_escape_string($this->name, $this->db).'", ';
		$sql.= 'expires = '.(time() + $this->lifetime).', ';
		$sql.= 'data = "'.mysql_real_escape_string($data, $this->db).'" ';
		$sql.= 'on duplicate key update expires = values(expires), data = values(data)';
		// Run it and return true if it was successful
		$result = mysql_query($sql, $this->db);
		if ($result !== false and mysql_affected_rows($this->db) > 0)
			$retval = true;
		@mysql_free_result($result);
		return $retval;
	}

	public function Destroy($id)
	{
		// Remove this session from the database
		$result = mysql_query('delete from `'.$this->table.'` where id = "'.mysql_real_escape_string($id, $this->db).'" and name = "'.mysql_real_escape_string($this->name, $this->db).'"', $this->db);
		if ($result !== false and mysql_affected_rows($this->db) > 0)
			return true;
		return false;
	}

	public function GC($lifetime)
	{
		// Remove any sessions that have expired
		$result = mysql_query('delete from `'.$this->table.'` where expires < '.time(), $this->db);
		return ($result === false ? 0 : mysql_affected_rows($this->db));
	}
}

http://jmp.li/

For those who care… it’s written in PHP, uses MySQL for storage but the destinations are cached at runtime for efficiency.

“Spam with Cheese”, ©kris247

If you’re using PHP you want PHPMailer. If you’re using something else there’s probably an equivalent library (Google is your friend). However, regardless of how you do it you should always consider the impact of your email activities on your users. Unwanted email is one of the biggest problems on the Internet today and the more you can do to present your website as a responsible sender of email the better.

Content

There are essentially two types of email that you might send out to the users of your website: operational and non-operational. The purpose and content of the two differ greatly and it’s important to understand the purpose of each to ensure your users understand why they’re getting them and what action (if any) they need to take when they do.

Operational Emails

The term operational emails refers to emails that directly relate to the service you are providing the user. For example this would include welcome messages, order acknowledgements and reminders that you may send to users in response to their actions or other events.

Successful operational emails are the ones that keep it simple. You’re sending them because they provide value for the user, so avoid the temptation to load them up with marketing information.

• Get straight to the point

  You’re sending this email because you need to tell the user something, so tell them. If you really need to add other stuff like marketing messages be sure to do it low key and after the primary content. The worst thing that can happen with your operational emails is that your users start ignoring them because the signal-to-noise ratio is too low.

• Avoid HTML

  Ask anyone in sales or marketing and they’ll tell you that to engage people you need flashy graphics and pleasing colours, and at times they’re right. However, when it comes to operational emails your users are already users - they’re already engaged. Plain text is your best option. You can get the point across quickly, the message is less likely to be marked as spam and users won’t get any security warnings when they open it.

  One thing you do need to ensure when using plain text is that your links are short to avoid them wrapping and becoming unclickable.

  Note that not using HTML for these emails is probably more of a personal preference, but in my opinion while HTML email is a necessary evil for sales and marketing messages it has no place in operational emails.

Sales & Marketing Emails

Promotional emails can be a very effective way of reminding your users that you’re there. I’m sure I have accounts on many websites I never visit and that haven’t even crossed my mind lately, but it’s likely if I received an occasional email from them I’d go visit them. I may just go back to delete my account, but surely that’s better than account rot. On the other hand it may remind me why I signed up in the first place and I could become an active user again.

Emails can also be a great medium through which to inform your users of new features on your site, or long-standing features that aren’t getting used. And don’t forget that they also provide the opportunity to push the features of your site that make you money.

Evil reasons aside (because we all know sales and marketing people are an evil bunch), regular contact with your users is more likely to engage them with your website. Nothing you do on the site itself can have the same effect, but you have to do it right to prevent getting bitten by consequences.

The keys to success with sales and marketing emails differ greatly depending on the subject and audience.

• Don’t let the message get lost in the pretty pictures

  While less pointed than operational emails promotional emails still carry a message to your users and it’s important that they get it. If you look at an email you want to send and you can’t immediately see what it’s telling you chances are it will be ignored by a fair proportion of recipients. Time is precious and people are rarely willing to give emails longer than a few seconds to assert their importance.

• Use HTML but make sure it degrades well

  You probably realise that by using HTML you can make your email more engaging, but it’s all too easy to ignore the realities of the security-concious email clients that are out there. Here are some pointers to ensuring maximum compatibility…

  • Test it in as many clients as possible.
  • Check it with images turned off, with background images turned off, with CSS turned off and combinations of all three.
  • If you’re loading images off a remote server remember that by default most email clients will not show them without the user saying it can.
  • Ensure all images have alt tags - including transparent images where you should set it to a single space.
  • Make it a complete HTML page including a doctype.
  • Provide a link at the very top of the email that goes to the email on a web server. Some people will trust that link over clicking the big scary button in their email client that makes it look like your email is trying to take over their computer.

Technicalities

More important (from a potential problems point of view) than the content of the emails you send is the process and procedures you use to actually send them. Most of this should sound like common sense but I think it’s important to state the obvious. The public view of commercial email, whether unsolicited or not is well-known, so unless you want to give your website a bad reputation you need to take care to do it properly.

Recipient management

Track your recipient list carefully. If someone tells you they don’t want your email, don’t send them email. There is no commercial value in sending email to someone who doesn’t want it, but the potential damage it can cause is extensive.

Unsubscribes

You’ll already know that you need to provide unsubscribe instructions in each email you send. For operational emails it may be as simple as “you have an account and to use it you need to get these emails”. For promotional emails you need to provide a way for people to unsubscribe from them but continue to receive operational emails.

When someone does unsubscribe, honour it. In my opinion it’s a good idea to keep a separate list of addresses that have unsubscribed as well as noting it against the user on your website. Whenever you send an email you should check to see if the recipient is in that separate unsubscribed list first.

Bounces

Track these too. Email can bounce for a variety of reasons. It could be that the address really doesn’t exist, or it could be because the mailbox is full. Either way you need to have a procedure in place to deal with addresses that bounce.

Given that not all bounces mean the address is not valid it’s a good idea to have a bounce threshold. Record bounces and when you get more than 1 (or more than 2 if you want to be more tolerant) for a given address mark them as bounced and stop sending email to it. This will prevent your mail server from having to do more work than it needs to.

I’ve heard several people suggest that it’s a good idea to periodically flush bounced addresses. The argument centres around the possibility that you might mark perfectly valid addresses as bounced in fairly rare circumstances. The idea is that you unmark bounced addresses after some random period of time, thereby getting back any that were incorrectly marked as bounced. Personally I don’t think it’s worth it, but if your bounce rate is low it can’t hurt. Just be sure not to apply the same logic to unsubscribed addresses!

Email structure

Well-behaved emails are those that have proper well-formed headers. The following list highlights the really important ones…

• Envelope sender

  A carefully crafted envelope sender is the best way to identify bounces when they come in. Take the following address…

  bounce+listname+messageid+john=doe.com@listserver.com

  Set up an alias called bounce that passes the email to a script. That script then does the following…

  • Remove the @ and everything after it.
  • Split what remains by + with a maximum of 3 elements. Limiting it to 3 elements allows for + signs in the users email address.
  • The first element is the name of the list they’re bouncing from.
  • The second element is the message ID they’re bouncing from. This part can be removed if you have no need to tie bounces to individual messages.
  • The last element is the email address in question encoded by replacing the @ with an =. To decode it ensure that you only change the last = to an @ as an = is perfectly valid in the user part.
  • Take whatever steps are required to mark that email address as bounced from that list.

  Technically you can probably remove the need for the list name and message ID because if an address bounces for one list it’s no different to it bouncing from another list. The same goes for the message ID. I use this to record events against a given message, but that’s only for metrics - it serves no functional purpose.

• Content

  If you’re sending HTML be sure to send a plain text alternative along with it. It doesn’t need to be the same content, it can be as simple as…

  This email is in HTML format which your email client is not displaying. To view this email click on this link.

  http://url.to/web/based/version/of/the/email

  Keep the URL as short as possible to avoid wrapping. Make sure you also include the unsubscribe instructions in the plain text content.

Sending email with PHP

Yeah, I know, most of the rest of this article has had nothing to do with PHP, but here’s where it comes on-topic. First let’s get one thing straight… the built-in mail function sucks.

PHPMailer is a great bit of code that simplifies creating and sending properly formed emails and I always recommend it unless you really understand email. If you know what you’re doing you can easily do everything yourself.

The one piece of advice I’d give is to make sure the SMTP server you’re dumping the messages to in the first instance will accept them with minimal delay. As long as you’ve set up your envelope sender as described above you’re far better off allowing the MTA to decide to bounce messages in its own time than you are waiting for it to do it as your script is sending them.

Other tips

Here are a few things to think about when sending bulk email.

Don’t over-complicate your unsubscribe process

If someone wants to unsubscribe from your list you need to make it as easy as possible. They don’t want your email - there’s no commercial value in keeping them subscribed. Your unsubscribe process should ideally take just one-click and certainly no more than two.

Don’t delay removing them from the list. Nothing grates me more in this area than a list that states it may take a few weeks for an unsubscribe request to be honoured. There’s never a valid reason why it would take that long.

Explain why you have their email address

You got their email address from somewhere. Hopefully they gave it to you willingly. In every email you send remind them why you have it. Put that right next to the unsubscribe instructions. It shows them that you’re not blindly flinging messages out without caring where they’re going.

Don’t ever use purchased lists

If you didn’t gather the addresses you’re sending to then you’re a spammer in my book regardless of the content of your emails. In addition you’ll find it difficult to justify why you sent them email if anyone complains (see the next point). If you have something to say that people want to hear you shouldn’t have any trouble gathering the email addresses of willing users.

Deal with spam complaints properly

If you get people complaining that you’re spamming them (and you will), make sure you respond to each one personally. If you can trace why their email address was used tell them. Provide details of the unsubscribe procedure and also offer to unsubscribe their address for them if they simply reply to you requesting that. If you’re doing everything else right these complaints should be quite rare, but I think it’s worth putting in the small amount of effort it takes to deal with them properly and personally. One of the lists I manage contains over 600,000 addresses and we’ve never had more than 4 spam complaints from any one message sent.

It’s important to note that complaints of this nature are usually sent through or copied to your hosting provider or ISP. Get too many and they’ll start to take notice and there may be damaging consequences so deal with them quickly and keep all parties informed.

That’s all folks

I hope this article has given you some pointers to help you on your way to being a good citizen in the world of bulk email. Feel free to leave a comment if you have any questions or you think I’ve missed something.

HDR example by Jared Earle, used with permission

The main reason this post exists is due to a request from someone on the PHP-General list. This code is not intended to be bug-free or extensively tested or indeed anything. Treat it as you would any other experimental code.

Design

The basic design of this system is based around a base class called Table. Fundamentally the Table class wraps a database table row. When using a system like this it is important to keep in mind what the memory implications are, but more on that later.

When an instance of a subclass of the Table class is created, it gets the table definition from either the database or a definition cache. The cache is file-based and is considerably quicker than getting the definition from the database every time. The definition for any given table is loaded only once per request. The only important implication of this is that if the table definition changes you need to delete the cache file to force it to be loaded from the database again.

One last thing… the class relies upon the primary key to perform updates, so it’s vital that any tables you want to use with this system have one.

Ok, nuff talk, let’s get to the code!

Implementation

Probably the easiest thing to do is to go through the two classes piece by piece. Rather than describe the code and force you to match up my ramblings with a separate file of code, I’ve commented the source liberally. Let’s start with the Table class.

<?php
 // Table: An ActiveRecord-style DB abstraction class
 // Copyright (c) 2005-2006 Stuart Dallas
 // Released into the public domain with absolutely no warranty, explicit, implied or otherwise
 // Use at your own risk!! 

// If you do use this code please drop an email to code@stut.net and let me know why 
 // Patches, comments, suggestions, questions, etc are welcomed

// The MODEL_CACHE_DIR is where the table definitions get cached. This can be anywhere you like, defaults to cache/
 // in the same location as this file. Obviously the web user (usually nobody or www) needs to have write access to
 // this directory.
 define('MODEL_CACHE_DIR', dirname(__FILE__).'/cache/');
 // Make sure the directory exists, or try to create it if not
 if (!file_exists(MODEL_CACHE_DIR))
 	mkdir(MODEL_CACHE_DIR) or die('Failed to create model cache directory on line '.__LINE__.' of '.__FILE__);

class Table
 {
 	protected $table = '';					// What table does this map to
 	protected $idfield = 'id';				// If there is an ID field, but it's not called id, override this
 	protected $readonly = false;			// Access to this table is read only
 	protected $data = false;				// Internal array of row data
 	protected $dirty = false;				// Is this row dirty?
 	protected $disregarddirty = false;		// Do we care that it's dirty?
 	protected $isnew = true;				// Is it a new row?
 	protected $customfieldtypes = array();	// Overrides of the default field types (for automatic form creation)

protected static $fields = array();		// Per-request cache of the table definitions

// Init is called by the constructors of subclasses
 	// It is responsible for loading the table definition
 	public function Init($classname, $conditions = '', $order = '')
 	{
 		// Have we been called statically or dynamically?
 		// Either way we need an instance to work with
 		if (isset($this))
 			$obj = &$this;
 		else
 			$obj = new $classname();

// The table variable should be set by the subclass, if not use the class name
 		if ($obj->table == '')
 			$obj->table = strtolower($classname);

// Only load the field defs if this model has not been used yet in this request
 		if (!isset(self::$fields[$obj->table]))
 		{
 			// Build the base filename of the cache files for this table
 			$cachefilename = MODEL_CACHE_DIR.$obj->table;

// Does the field definition cache file exist? If not we need to build it
 			if (!file_exists($cachefilename.'.fields'))
 			{
 				// Initialise the cache (stored statically in the Table class)
 				self::$fields[$obj->table]['fields'] = array();
 				self::$fields[$obj->table]['autonumber'] = array();
 				self::$fields[$obj->table]['primarykey'] = array();

// Get the field definitions
 				$query = mysql_query('show columns from '.$obj->table);
 				while ($row = mysql_fetch_assoc($query))
 				{
 					// We store auto_number fields separately for use when creating new rows
 					if (strpos($row['Extra'], 'auto_increment') !== false)
 						self::$fields[$obj->table]['autonumber'][] = $row['Field'];
 					else
 						self::$fields[$obj->table]['fields'][$row['Field']] = $row;
 				}

// Get the primary key fields
 				$query = mysql_query('show indexes from '.$obj->table);
 				while ($row = mysql_fetch_assoc($query))
 				{
 					if ($row['Key_name'] == 'PRIMARY')
 						self::$fields[$obj->table]['primarykey'][] = $row['Column_name'];
 				}

// Now save the definition in files in the model cache directory
 				file_put_contents($cachefilename.'.fields', serialize(self::$fields[$obj->table]['fields']));
 				file_put_contents($cachefilename.'.autonumber', serialize(self::$fields[$obj->table]['autonumber']));
 				file_put_contents($cachefilename.'.primarykey', serialize(self::$fields[$obj->table]['primarykey']));
 			}
 			else
 			{
 				// The cache files exist, load them
 				self::$fields[$obj->table]['fields'] = unserialize(file_get_contents($cachefilename.'.fields'));
 				self::$fields[$obj->table]['autonumber'] = unserialize(file_get_contents($cachefilename.'.autonumber'));
 				self::$fields[$obj->table]['primarykey'] = unserialize(file_get_contents($cachefilename.'.primarykey'));
 			}
 		}

// Did we get given conditions?
 		if (strlen($conditions) > 0)
 		{
 			// If it's numeric, use it as an ID and build a where clause. This relies upon the idfield member variable that
 			// should be overridden in subclasses if the ID field is not named 'id'
 			if (is_numeric($conditions))
 			{
 				$conditions = $this->idfield.' = '.Table::Escape($conditions);
 			}

// Try to find a row matching the conditions
 			if ($obj->FindFirst($conditions, $order) === false)
 			{
 				// Couldn't find one, reset this object so it's an unsaved new row
 				$obj->Clear();
 			}
 		}
 		else
 		{
 			// No conditions, it's an unsaved new row
 			if($obj->data === false) $obj->Clear();
 		}
 	}

// The destructor does nothing more than a sanity check to see if this row is dirty (i.e. contains unsaved data), in which
 	// case it raises an error. The disregarddirty flag can be used to disable this where destroying a dirty object is expected
 	public function __destruct()
 	{
 		if ($this->dirty && !$this->disregarddirty)
 			trigger_error(get_class($this).'.__destruct: Dirty object being released');
 	}

// Ahh, magic functions!!
 	// This one allows you to use OO syntax to access fields, e.g. $obj->id will get you the id field
 	public function __get($field)
 	{
 		return (isset($this->data[$field]) ? $this->data[$field] : '');
 	}

// The other half of __get is __set. This method is called if you do something like $obj->id = 100
 	public function __set($field, $value)
 	{
 		// If we're read only then changing the data is not allowed
 		if ($this->readonly)
 		{
 			trigger_error(get_class($this).'.__set: Attempt to modify a readonly object');
 		}
 		// If the row is not new then the primary key is read only
 		elseif (!$this->isnew and in_array($field, self::$fields[$this->table]['primarykey']))
 		{
 			trigger_error(get_class($this).'.__set: Attempt to set primary key field "'.$field.'"');
 		}
 		// Now we check to make sure the attribute being set actually exists (i.e. is in the table fields or is already in the
 		// data array)
 		elseif (isset(self::$fields[$this->table]['fields'][$field]) or isset($this->data[$field]))
 		{
 			if (!isset($this->data[$field]) or $this->data[$field] != $value)
 				$this->dirty = true;
 			$this->data[$field] = $value;
 		}
 		// If we get here then we don't know anything about the field being set - that's an error that is!
 		else
 		{
 			trigger_error(get_class($this).'.__set: Unknown field "'.$field.'"');
 		}
 	}

// LoadFromArray does what it says on the tin. It fills in the data for this record from an array
 	private function LoadFromArray($arr)
 	{
 		$this->data = array();

// Only allow fields we know about, ignore anything else
 		foreach (array_keys(self::$fields[$this->table]['fields']) as $field)
 			if (isset($arr[$field]))
 				$this->data[$field] = $arr[$field];
 		foreach (self::$fields[$this->table]['autonumber'] as $field)
 			if (isset($arr[$field]))
 				$this->data[$field] = $arr[$field];

// At first glance these might seem wrong, but this method is used when reading > 1 row (see the FindAll method) and since it's
 		// a private method we know the data source will always be the database, so it's not new and it's not dirty
 		$this->dirty = false;
 		$this->isnew = false;

// Call table-specific translation
 		$this->AfterLoad();
 	}

// Call this function to disable the error generated when a dirty object is destructed
 	public function DisregardDirty()
 	{
 		$this->disregarddirty = true;
 	}

// Clear the object of data.
 	protected function Clear()
 	{
 		$this->data = array();
 	}

// Stubs for table-specific stuff
 	protected function AfterLoad() { }
 	protected function BeforeSave() { }
 	protected function AfterDelete($result) { }
 	protected function BeforeDelete() { }

// GetFieldType first looks in the customfieldtypes array to see if the subclass has overridden it before returning the
 	// field type from the table definition. If we don't know anything about the field, assume it's a string
 	public function GetFieldType($field)
 	{
 		if (isset($this->customfieldtypes[$field]))
 			return $this->customfieldtypes[$field];
 		if (isset(self::$fields[$this->table]['fields'][$field]['Type']))
 			return self::$fields[$this->table]['fields'][$field]['Type'];
 		return 'string';
 	}

// GetValueFromDB will re-fetch a single value from the DB - useful for flags, locks, etc
 	public function GetValueFromDB($field)
 	{
 		$retval = $this->GetValuesFromDB(array($field));
 		return $retval[$field];
 	}

// GetValuesFromDB will get a given set of fields from this row in the table
 	// Note that it does not update the internal data
 	public function GetValuesFromDB($fieldlist = array())
 	{
 		$retval = false;
 		if (!$this->isnew and count($fieldlist) > 0)
 		{
 			$sql = 'select '.implode(',', $fieldlist).' from '.$this->table.' where '.$this->PrimaryKeyWhere();
 			$query = mysql_query($sql);
 			if ($query !== false and mysql_num_rows($query) == 1)
 			{
 				$row = mysql_fetch_assoc($query);
 				$retval = array();
 				foreach ($row as $key => $val)
 					$retval[$key] = $val;
 			}
 		}
 		return $retval;
 	}

// GetFieldList will produce an array containing the table definition
 	public function GetFieldList($pkey = true, $normal = true)
 	{
 		$retval = array();
 		if ($pkey) $retval['primarykey'] = self::$fields[$this->table]['primarykey'];
 		if ($normal) $retval['normal'] = self::$fields[$this->table]['fields'];
 		return $retval;
 	}

// Reload will update this object from the table
 	// Reloading a new row (duh!!) or reloading a dirty object will raise errors
 	public function Reload($ignoredirty = false)
 	{
 		if ($this->isnew)
 		{
 			trigger_error(get_class($this).'.Reload: Attempted to reload a new object');
 		}
 		else
 		{
 			if (!$ignoredirty and !$this->disregarddirty and $this->dirty)
 				trigger_error(get_class($this).'.Reload: Reloading a dirty object - changes lost');
 			// Reload from DB
 			$this->FindFirst($this->PrimaryKeyWhere());
 		}
 	}

// CreateInsertSQL is a helper function used to build insert statements
 	private function CreateInsertSQL($setfields)
 	{
 		return 'insert into '.$this->table.' set '.implode(', ', $setfields);
 	}

// Save this row
 	public function Save()
 	{
 		$retval = false;

// Can't save a read only row
 		if ($this->readonly)
 		{
 			trigger_error(get_class($this).'.Save: Attempt to save a readonly object');
 		}
 		// Are we dirty?
 		elseif ($this->dirty)
 		{
 			// Call table-specific translation
 			$this->BeforeSave();

// Get the fields
 			$setfields = array();
 			foreach (array_keys(self::$fields[$this->table]['fields']) as $field)
 			{
 				if (isset($this->data[$field]))
 					$setfields[$field] = $field.' = '.self::Escape($this->data[$field]);
 			}

// Is this a new row?
 			if ($this->isnew)
 			{
 				// Insert a new row
 				$sql = $this->CreateInsertSQL($setfields);
 			}
 			else
 			{
 				// Update existing row
 				$sql = 'update '.$this->table.' set '.implode(', ', $setfields).' where '.$this->PrimaryKeyWhere();
 			}

$result = mysql_query($sql);
 			if ($result === false)
 			{
 				// Something bad happened!
 				trigger_error(get_class($this).'.Save: Failed to save object - '.mysql_error());
 				$retval = false;
 			}
 			else
 			{
 				// Saved successfully, we're now clean
 				$this->dirty = false;
 				$retval = true;

// If this was a new row we need to grab the auto_number'd id
 				if ($this->isnew)
 				{
 					$this->data[$this->idfield] = mysql_insert_id();
 					// We're no longer a new row
 					$this->isnew = false;
 				}
 			}

// Call table-specific stuff
 			$this->AfterLoad();
 		}
 		else
 		{
 			// Not dirty, call it a success!
 			$retval = true;
 		}

return $retval;
 	}

// Delete will delete this row from the table
 	public function Delete()
 	{
 		$retval = false;
 		// Can't delete a new row, it doesn't actually exist yet!
 		if ($this->isnew)
 		{
 			trigger_error(get_class($this).'.Delete: Attempted to delete a new object');
 		}
 		else
 		{
 			// Call table-specific stuff
 			$this->BeforeDelete();
 			// Do the delete
 			$sql = 'delete from '.$this->table.' where '.$this->PrimaryKeyWhere();
 			$retval = mysql_query($sql);
 			// Call table-specific stuff
 			$this->AfterDelete($retval);
 		}
 		return $retval;
 	}

// PrimaryKeyWhere builds a where clause from the fields in the primary key
 	// This effectively produces a where clause that will retrieve the row this object is representing
 	public function PrimaryKeyWhere()
 	{
 		$wherefields = array();
 		foreach (self::$fields[$this->table]['primarykey'] as $field)
 			$wherefields[] = $field.' = '.self::Escape($this->data[$field]);
 		return '('.implode(' and ', $wherefields).')';
 	}

// FindAll takes a set of conditions in the form of a where clause, a limit clause and an order specification,
 	// builds a query from them and executes it. The rows returned are used to create an array of objects which is
 	// then returned
 	// Note that this method can only be called on subclasses - it cannot be called directly on the Table class
 	public function FindAll($conditions = '', $limit = '', $order = '')
 	{
 		$sql = 'select * from '.$this->table;
 		if (strlen($conditions) > 0)
 			$sql .= ' where '.$conditions;

if (strlen($order) > 0)
 			$sql .= ' order by '.$order;

if (strlen($limit) > 0)
 			$sql .= ' limit '.$limit;

$query = mysql_query($sql);

// Errors will currently cause an error to be raised. This may not be ideal for your application, you may need
 		// to change how these are handled
 		if (!$query)
 			trigger_error('MySQL error in '.get_class($this).'::FindAll: '.mysql_error());

// If the query got no rows return an empty array
 		if (mysql_num_rows($query) == 0)
 			return array();

$classname = get_class($this);
 		$retval = array();
 		while ($row = mysql_fetch_assoc($query))
 		{
 			$obj = new $classname();
 			$obj->LoadFromArray($row);
 			$retval[] = $obj;
 		}
 		return $retval;
 	}

// FindFirst does the same as FindAll but only gets a single row and returns a single object
 	public function FindFirst($conditions = '', $order = '')
 	{
 		$sql = 'select * from '.$this->table;
 		if (strlen($conditions) > 0)
 			$sql .= ' where '.$conditions;

if (strlen($order) > 0)
 			$sql .= ' order by '.$order;

$sql .= ' limit 1';

$query = mysql_query($sql);

// Errors will currently cause an error to be raised. This may not be ideal for your application, you may need
 		// to change how these are handled
 		if (!$query)
 			trigger_error('MySQL error in '.get_class($this).'::FindFirst: '.mysql_error());

// If the query got no rows return false rather than a new empty object
 		if (mysql_num_rows($query) == 0)
 			return false;

$row = mysql_fetch_assoc($query);
 		$this->LoadFromArray($row);

return $this;
 	}

// Paged is similar to FindAll but it will get a certain range of rows given a page number and the number of rows
 	// on each page. Returns an array where [0] is an array of rows, [1] is the current page number (in case it was
 	// adjusted) and [2] is the total number of pages available
 	public function Paged($page = 1, $perpage = 10, $conditions = '', $order = '')
 	{
 		// Get the total count
 		$sql = 'select count(1) from '.$this->table;
 		if (strlen($conditions) > 0)
 			$sql .= ' where '.$conditions;
 		$query = mysql_query($sql);

// Query failed, raise an error
 		if (!$query)
 			trigger_error('MySQL error in '.get_class($this).'::Paged: '.mysql_error());

// Because it's a count query this should never happen, but handle nicely just in case
 		if (mysql_num_rows($query) == 0)
 			return array(array(), 1, 1);

$row = mysql_fetch_array($query);
 		$rowcount = $row[0];
 		// Return if there are no matching rows
 		if ($rowcount == 0)
 			return array(array(), 1, 1);

// Make sure the requested page number is in range
 		$totalpages = ceil($rowcount / $perpage);
 		if ($page > $totalpages) $page = $totalpages;
 		if ($page < 1) $page = 1;

// Build the query
 		$sql = 'select * from '.$this->table;
 		if (strlen($conditions) > 0)
 			$sql .= ' where '.$conditions;

if (strlen($order) > 0)
 			$sql .= ' order by '.$order;

$sql .= ' limit '.(($page-1) * $perpage).','.$perpage;

$query = mysql_query($sql);

// Query failed, raise an error
 		if (!$query)
 			trigger_error('MySQL error in '.get_class($this).'::Paged: '.mysql_error());

// No rows returned, this shouldn't be possible but handle nicely just in case
 		if (mysql_num_rows($query) == 0)
 			return array(array(), 1, 1);

// Create the object array
 		$classname = get_class($this);
 		$retval = array();
 		while ($row = mysql_fetch_assoc($query))
 		{
 			$obj = new $classname();
 			$obj->LoadFromArray($row);
 			$retval[] = $obj;
 		}

// Return the rows, the page number and the number of pages
 		return array($retval, $page, $totalpages);
 	}

// Count returns the number of rows that match a condition
 	public function Count($conditions)
 	{
 		$sql = 'select count(*) as count from '.$this->table;
 		if (strlen($conditions) > 0)
 			$sql .= ' where '.$conditions;

$query = mysql_query($sql);
 		if (!$query or mysql_num_rows($query) == 0)
 			return false;

$row = mysql_fetch_assoc($query);
 		return $row['count'];
 	}

// Is this row new?
 	public function IsNew()
 	{
 		return $this->isnew;
 	}

//////////////////////////////
 	// Static utility functions //
 	//////////////////////////////

// Escape should be used to escape all values used in conditions
 	static public function Escape($var)
 	{
 		return '"'.mysql_real_escape_string($var).'"';
 	}

// MakeLike returns a like query for a given var and val
 	static public function MakeLike($var, $val)
 	{
 		return '(`'.$var.'` like "%'.mysql_real_escape_string($val).'%")';
 	}

// MakeLikes takes an array of vars and a single val and returns a set of likes combined by op
 	static public function MakeLikes($vars, $val, $op = 'or')
 	{
 		$likes = array();
 		foreach ($vars as $var)
 			$likes[] = self::MakeLike($var, $val);
 		return '('.implode(' '.$op.' ', $likes).')';
 	}

// Lock and Unlock wrap the table locking system
 	static protected function Lock($tables = false)
 	{
 		if ($tables === false)
 			trigger_error("Table::Lock called without a table to lock");

if (!is_array($tables))
 			$tables = array($tables);
 		return mysql_query('lock tables `'.implode('`,`', $tables).'`');
 	}
 	static protected function Unlock()
 	{
 		return mysql_query('unlock tables');
 	}

// GetSingleValue will return the first value of the first row returned by the provided SQL
 	// Caller should make sure it's only getting one field and one row
 	static public function & GetSingleValue($sql)
 	{
 		$query = mysql_query($sql);
 		if ($query === false)
 		{
 			trigger_error('Query failed: '.mysql_error(), E_USER_ERROR);
 			exit;
 		}
 		if (mysql_num_rows($query) == 0)
 			return false;
 		$retval = mysql_fetch_array($query);
 		mysql_free_result($query);
 		return $retval[0];
 	}

// GetSingle will return an associative array containing the first row returned by the provided SQL
 	// Caller should make sure it's only getting one row
 	static public function & GetSingle($sql)
 	{
 		$query = mysql_query($sql);
 		if ($query === false)
 		{
 			trigger_error('Query failed: '.mysql_error(), E_USER_ERROR);
 			exit;
 		}
 		if (mysql_num_rows($query) == 0)
 			return array();
 		$retval = mysql_fetch_assoc($query);
 		mysql_free_result($query);
 		return $retval;
 	}

// GetMultiple will return an array of associative arrays containing every row returned by the provided SQL
 	// Be careful not to get too many rows with this method - it loads them all into memory!!
 	static public function & GetMultiple($sql)
 	{
 		$query = mysql_query($sql);
 		if ($query === false)
 		{
 			trigger_error('Query failed: '.mysql_error(), E_USER_ERROR);
 			exit;
 		}
 		$retval = array();
 		if (mysql_num_rows($query) > 0)
 		{
 			while ($row = mysql_fetch_assoc($query))
 			$retval[] = $row;
 		}
 		mysql_free_result($query);
 		return $retval;
 	}

// GetSingleColumn will return an array containing the first field of each row returned by the provided SQL
 	// Be careful not to get too many rows with this method - it loads them all into memory
 	static public function & GetSingleColumn($sql)
 	{
 		$query = mysql_query($sql);
 		if ($query === false)
 		{
 			trigger_error('Query failed: '.mysql_error(), E_USER_ERROR);
 			exit;
 		}
 		$retval = array();
 		if (mysql_num_rows($query) > 0)
 		{
 			while ($row = mysql_fetch_array($query))
 			$retval[] = $row[0];
 		}
 		mysql_free_result($query);
 		return $retval;
 	}

// Modify is intended to execute a SQL statement that will make a change (insert, update, alter, etc)
 	static public function Modify($sql)
 	{
 		$query = mysql_query($sql);
 		if ($query === false)
 			return false;
 		return true;
 	}

// ModifyWithAutonumber is the same as Modify but returns the autonumber ID
 	static public function ModifyWithAutonumber($sql)
 	{
 		$query = mysql_query($sql);
 		if ($query === false)
 			return false;
 		return mysql_insert_id();
 	}
 }

And that concludes the Table class, I hope you enjoyed the ride. Seriously though, it’s not too complicated and it really does make working with small numbers of rows a lot easier.

A quick mention of resource usage

Before we get on to the example subclass I just wanted to mention the resource implications of this class. Clearly this method of accessing a database uses more memory and be a bit more CPU-intensive than simply using the MySQL functions where they are needed. However, for me at least, the benefits far outweigh the costs. And from what I’ve seen the costs are fairly minimal anyway.

The key thing is to be a bit careful about what the code you’re writing will actually do. Is it going to retrieve 10,000 rows meaning it will instantiate 10,000 objects? If so then you’re better off using another method. If, on the other hand, you’re retrieving a single row that will be stored in the session and may get changed occasionally during its lifetime, this is absolutely worth the minimal cost in efficiency. I’ll go into an example of this type of usage for the Account class in the next section, and I’ll explain how it helps with that type of situation.

Something I have tried to avoid is abstracting the database too much. This class is not meant to make it easy to switch between database systems. While it would be relatively trivial to convert it to use MSSQL or PostgreSQL, some work would be needed anywhere a limit clause has been used, or a MySQL-specific feature has been used in some conditions. But it’s ok since that was not my aim. There are plenty of other database abstraction projects out there, and from my experience each one sucks just as much as the others. But I digress.

I was trying to explain, via a lengthy detour, why you won’t find Open, Next and Close methods in this class. It’s not what I was trying to do. If I have a situation where those methods would be needed I’d prefer to use mysql_(p)connect, mysql_fetch_assoc and mysql_close rather than waste time trying to replace something perfectly adequate for the rare times I’d need them.

Right, mini-rant over. On to the account class.

<?php
 // Model: Account 

// Pull in the table definition
 require_once('table.class.php');

class Account extends Table
 {
 	// The table we're mapping to is called accounts
 	protected $table = 'accounts';
 	// We have a number of fields we want to treat differently
 	// Note that these definitions don't affect how the data is treated, it just changes what is reported
 	// by the GetFieldType method in the Table class - this was added to allow automatic generation of
 	// forms
 	// An array indicates something akin to an enumeration where the actual value used can be defined
 	// differently (look at ACM in AccountType)
 	protected $customfieldtypes = array('Status' => array('Created', 'Active', 'Expired', 'Deleted'),
 										'Created' => 'date',
 										'Expires' => 'date',
 										'AccountType' => array('Full', 'Demo', 'ACM' => 'acm'),
 										);

// AfterLoad is called whenever the Table class completes loading of the data
 	// It can be used to...
 	protected function AfterLoad()
 	{
 		// ...enforce consistency...
 		if (isset($this->data['AccountType']))
 		{
 			// If ACM, the accounttype should be lowercase
 			if (strtolower($this->data['AccountType']) == 'acm')
 				$this->data['AccountType'] = 'acm';
 		}

// ...present data to consumers in a different format to that which is stored in the table...
 		if (isset($this->data['Created']) and $this->data['Created'] > 0)
 			$this->data['Created'] = date('Y-m-d', $this->data['Created']);

if (isset($this->data['Expires']) and $this->data['Expires'] > 0)
 			$this->data['Expires'] = date('Y-m-d', $this->data['Expires']);

// ...including complex types...
 		if (isset($this->data['OtherInfo']))
 			$this->data['OtherInfo'] = unserialize($this->data['OtherInfo']);

// ...and it can be used to create pseudo fields that do not exist in the table but may exist in other tables
 		$this->data['projects'] = array();
 	}

// BeforeSave is called by the Table class right before it saves the data back to the table
 	// It has the reverse purpose of AfterLoad, so you can...
 	protected function BeforeSave()
 	{
 		// ...store complex types...
 		if (isset($this->data['OtherInfo']) and is_array($this->data['OtherInfo']))
 			$this->data['OtherInfo'] = serialize($this->data['OtherInfo']);

// ...convert data to a format suitable for storage in a table...
 		if (isset($this->data['Expires']) and strlen($this->data['Expires']) > 0 and $this->data['Expires'] != 0)
 			$this->data['Expires'] = strtotime($this->data['Expires']);

// ...and forcing default values in new rows
 		if ($this->isnew)
 		{
 			$this->data['Created'] = time();
 			if (!isset($this->data['Status'])) $this->data['Status'] = 'Created';
 		}
 		else
 		{
 			if (isset($this->data['Created']) and strlen($this->data['Created']) > 0 and $this->data['Created'] != 0)
 				$this->data['Created'] = strtotime($this->data['Created']);
 		}

// Note the absense of any reference to the projects variable
 		// This is fine since the Save method of the Table class uses its own internal list of fields to decide which parts of
 		// the data to save to the table
 	}

// In addition to overriding methods in the Table class, we can create methods that are specific to this particular table
 	// For example, this method will return true only if the AccountType is set to acm (Account Manager)
 	public function IsACM()
 	{
 		return (isset($this->data['AccountType']) and $this->data['AccountType'] == 'acm');
 	}

// Methods can also return related rows
 	// For example, GetACM will return an Account object representing this objects Account Manager
 	public function & GetACM()
 	{
 		$retval = false;
 		if ($this->data['ACM'] > 0)
 		{
 			$retval = new Account('id = '.$this->data['ACM']);
 		}
 		return $retval;
 	}

// In true OO tradition, any method in this class should be related to an Account
 	// For example, IsExpired will return true if the account has expired...
 	public function IsExpired()
 	{
 		return (isset($this->data['Expires']) and $this->data['Expires'] != 0 and strtotime($this->data['Expires']) < time());
 	}

// ...MarkDeleted will set the status of the Account and save it back to the database...
 	public function MarkDeleted()
 	{
 		$this->Status = 'Deleted';
 		// Note that calling Save will cause BeforeSave to be called, the data will then be saved and finally AfterLoad will be called
 		// This means that the member variable named data will be reset, along with any custom fields put in by AfterLoad
 		return $this->Save();
 	}

// ...performing actions like resetting the account password...
 	public function ResetPassword($password = '')
 	{
 		// If no password was given, generate a random one
 		$pwd = $password;
 		if (strlen($pwd) == 0)
 			$pwd = generatePassword(); // Function source omitted since it's irrelevant

// Save it
 		$this->Password = $pwd;
 		if (!$this->Save())
 			return false;

if ($password == '')
 		{
 			// Password was random, email it to the address held in the account
 			if (strlen($this->data['EmailAddress']) > 0)
 				mail($this->data['EmailAddress'], 'Password Updated', 'Your new password is: '.$pwd, "From: Support <support@example.com>", '-fsupport@example.com');
 		}

return true;
 	}

// ...getting or counting other records...
 	public function ACM_GetAccounts($countonly = false)
 	{
 		if ($countonly)
 		{
 			return $this->Count('ACM = '.self::Escape($this->data['id']));
 		}
 		else
 		{
 			return $this->FindAll('ACM = '.self::Escape($this->data['id']), '', 'name asc');
 		}
 	}

// ...ensuring that deletions get propogated to dependent data...
 	public function Destroy()
 	{
 		$accounts = $this->ACM_GetAccounts();
 		foreach ($accounts as $account)
 		{
 			$result = $account->Destroy();
 			if ($result !== true)
 				return $result;
 		}

// Call destroy on all projects first - Project is another class derived from Table
 		$tmp = new Project();
 		$projects = $tmp->FindAll('accountid = '.self::Escape($this->data['id']));
 		foreach ($projects as $project)
 		{
 			$result = $project->Destroy();
 			if ($result !== true)
 				return $result;
 		}
 		// Then delete this account
 		$result = $this->Delete();
 		if ($result !== true)
 			return 'Failed to delete account '.$this->data['id'];
 		return true;
 	}

// ...other functions omitted for clarity

// You can also define static methods
 	// Account::Current() will get you an account object from the session (see the next method, Login)
 	static public function & Current()
 	{
 		$retval = false;
 		if (isset($_SESSION['account']))
 			$retval = $_SESSION['account'];
 		return $retval;
 	}

// The Login method takes an email address and a password and tries to log the user in
 	// If login is successful it stores the Account object in the session so it can be retrieved by the Current method
 	static public function Login($email, $password)
 	{
 		$account = new Account();
 		if ($account->FindFirst('EmailAddress = '.Table::Escape($email).' and Password = '.Table::Escape($password)) !== false)
 		{
 			$_SESSION['account'] = &$account;
 			return true;
 		}
 		return false;
 	}

// Static functions can also be used to return multiple rows
 	// This one will return an array of objects containing the Account Manager records
 	static public function & GetACMs()
 	{
 		$account = new Account();
 		return $account->FindAll('AccountType = '.Table::Escape('acm'), '', 'name asc');
 	}

// The rest is exactly the same for every class that derives from Table - absolutely nothing needs changing from class to class,
 	// but it's vital that these exist - see the next bit of the article for an explanation

// The constructor takes conditions and order and passes them, along with the class name, to the Init method
 	public function __construct($conditions = '', $order = '') { $this->Init(__CLASS__, $conditions, $order); }
 	// The magic __wakeup method is called when an object is read from serialised data (e.g. the session). It also calls the Init
 	// method but just with the class name
 	public function __wakeup() { $this->Init(__CLASS__); }
 }

Ok, so there are a couple of oddities in there that need further explanation, and they both stem from the same problem. The PHP 5 implementation of objects means that inherited methods have an identity crisis. Say you have class A and class B, which extends A. In class A you have a method defined called WhoAmI which returns the name of the class. One possible implementation would use __CLASS__, another possibility would be the get_class function. You may also go as far as to pass $this into get_class. Let’s try an example…

 class A
 {
 	public function WhoAmI_1()
 	{
 		return __CLASS__;
 	} 

public function WhoAmI_2()
 	{
 		return get_class();
 	}

public function WhoAmI_3()
 	{
 		return get_class(\$this);
 	}
 }

class B extends A
 {
 }

print A::WhoAmI_1();
 print B::WhoAmI_1();

print A::WhoAmI_2();
 print B::WhoAmI_2();

Now, any sane and reasonable person with a basic knowledge of OOP would expect this to print “ABAB”. Yeah, I wish!! What you actually get is “AAAA”. Grrrrrrr!!

Now there are good reasons for why PHP does this, and from what I understand fixing it is a big job. I also understand that it’s been done in PHP 6 but is unlikely to make it into the 5.x branch, which is a shame.

So how do we get around that. Well, you probably noticed the WhoAmI_3 method in the above example that wasn’t used. Obviously you can’t use that method statically since it uses $this, so let’s add a few lines to it so we can try it out.

$a = new A();
$b = new B();
print $a->WhoAmI_3();
print $b->WhoAmI_3();

Perhaps unsurprisingly this gives us what we need: “AAAAAB”. But hang on a second, we had to create an instance of the object to do that. Not good. But unfortunately it’s the only way around it that I can find.

Hmm, you may be wondering what the heck I’m going on about. Look back at the source for account.class.php, around line 206 is a good example. This is the GetACMs method which is expected to return an array of Account objects representing the Account Manager rows. Notice how it creates a temporary instance if the Account class, calls FindAll on it and throws it away. Hopefully that’s clear now.

While this is a major PitA it’s not the end of the world. And despite several people telling me it’s a waste of resources and makes any other gains worthless, I still firmly believe that it’s a very small price to pay for the convenience this system provides. Also, the only workaround I’ve found that avoids having to create a temporary object is to repeat the code for FindAll in every derived class, and that’s something I’m not prepared to do. I’d rather lose a few microseconds of time and a few bytes of memory than have to do that. It’s bad enough having to remember to put the __construct and __wakeup lines into each one. Which leads me nicely on to those.

For the same reason that the temporary object is required, the __construct and __wakeup methods are required to be duplicated in each derived class. Daft though it may seem, but if you remove the __construct method from the Account class, the code new Account($id) would actually try to create a Table object which would have no way of knowing what table to use. Another PitA, but not so bad as long as you remember to copy those two lines into every class that derives from Table.

Hopefully, with the arrival of PHP 6 I should be able to modify these classes to work the way I had hoped they would.

Pop-ups are easy, you just call the javascript function window.open with the required parameters. To turn a pop-up into a pop-under is simple. On the page that’s loaded in the pop-up, simply add the following snippet…

<script type="text/javascript">
	self.blur();
</script>

That will cause the popped-up window to sink behind whatever opened it.

Note that I accept no responsibility for the complaints you’ll get from users if you start doing this. You’re on your own!

What’s causing it?

There is a configuration option called magic_quotes_gpc that is, for historic reasons, on by default. It’s this option that’s causing the backslashes. It effectively runs the addslashes function on all GET, POST and COOKIE data.

The reason for this is that many years ago this was the recommended way to escape incoming data before sending it to a SQL database. Having it done automatically could be seen to be useful. Personally I hate it - I’d rather know what’s happening to the data I’m dealing with and not rely on the server being configured in a certain way.

How do I stop it?

The simple answer is to turn magic_quotes_gpc off. Unfortunately not everyone has the luxury of being able to do that so the following chunk of code can be placed at the top of any file to check for and undo the addslashes on the GET, POST and COOKIE superglobals. This is pretty-much required to write run-anywhere PHP scripts.

if (get_magic_quotes_gpc()) {
  function stripslashes_array($array) {
    return  is_array($array)
           ?
            array_map('stripslashes_array', $array)
           :
            stripslashes($array);
  }  

  $_COOKIE = stripslashes_array($_COOKIE);
  $_FILES = stripslashes_array($_FILES);
  $_GET = stripslashes_array($_GET);
  $_POST = stripslashes_array($_POST);
  $_REQUEST = stripslashes_array($_REQUEST);
}

Rather than placing this in every file I’d recommend putting it in a separate file that you include at the top of each file. Alternatively you could use the auto_prepend_file php.ini directive to include it for all scripts.

Cal Henderson (of Flickr fame) wrote an excellent article a little while ago where he wrote a regular expression against the specification document that defines these things. As Cal points out, that specification is RFC822. Now this potentially has its problems because it was written in 1982 and the rules regarding valid characters in domain names have changed since then, but as far as I can tell his solution has then covered.

Check out his article: http://iamcal.com/publish/articles/php/parsing_email/

Hopefully Cal won’t mind if I reproduce the end result of his work here…

function is_valid_email_address($email)
{
$qtext = '[^\\x0d\\x22\\x5c\\x80-\\xff]';
$dtext = '[^\\x0d\\x5b-\\x5d\\x80-\\xff]';
$atom = '[^\\x00-\\x20\\x22\\x28\\x29\\x2c\\x2e\\x3a-\\x3c'.
 	'\\x3e\\x40\\x5b-\\x5d\\x7f-\\xff]+';
$quoted_pair = '\\x5c[\\x00-\\x7f]';
$domain_literal = "\\x5b($dtext|$quoted_pair)*\\x5d";
$quoted_string = "\\x22($qtext|$quoted_pair)*\\x22";
$domain_ref = $atom;
$sub_domain = "($domain_ref|$domain_literal)";
$word = "($atom|$quoted_string)";
$domain = "$sub_domain(\\x2e$sub_domain)*";
$local_part = "$word(\\x2e$word)*";
$addr_spec = "$local_part\\x40$domain";
return preg_match("!^$addr_spec$!", $email) ? 1 : 0;
}

For a recent project I needed a function to just validate a domain name, so I extracted the relevant parts and created the following function…

function is_valid_domain($domainname)
{
$dtext = '[^\\x0d\\x5b-\\x5d\\x80-\\xff]';
$atom = '[^\\x00-\\x20\\x22\\x28\\x29\\x2c\\x2e\\x3a-\\x3c'.
 	'\\x3e\\x40\\x5b-\\x5d\\x7f-\\xff]+';
$quoted_pair = '\\x5c[\\x00-\\x7f]';
$domain_literal = "\\x5b($dtext|$quoted_pair)*\\x5d"; 

$domain_ref = $atom;
$sub_domain = "($domain_ref|$domain_literal)";
$domain = "$sub_domain(\\x2e$sub_domain)*";
return preg_match("/^$domain$/i", $domainname) ? true : false;
}

Still a few bits that need sorting layout-wise (if the comment form below is the right width then I’ve done it!) but definitely a major improvement on the old new design.

I’ll shortly be migrating the articles into blog posts. I don’t think there’s a legitimate distinction to be made, and blog posts come bundled with comment and trackback abilities which is handy.