The original intent of the parser for me was to parse my iTunes’ library in PHP, so this example will show doing just that:

<?php

include("PlistParser.inc");

$parser = new plistParser();
$plist = $parser->parse(dirname(__FILE__) . "/iTunes.xml");
var_dump($plist);

And from that, the output is as follows:

array(8) {
  ["Major Version"]=>
  int(1)
  ["Minor Version"]=>
  int(1)
  ["Application Version"]=>
  string(5) "8.0.1"
  ["Features"]=>
  int(5)
  ["Show Content Ratings"]=>
  bool(true)
  ["Music Folder"]=>
  string(60) "file://localhost/Users/testUser/Music/iTunes/iTunes%20Music/"
  ["Library Persistent ID"]=>
  string(15) "C39203948AF3D3E"
  ["Tracks"]=>
  array(1) {
    [1]=>
    array(25) {
      ["Track ID"]=>
      int(1)
      ["Name"]=>
      string(8) "My Track"
      ["Artist"]=>
      string(9) "My Artist"
      ["Album"]=>
      string(8) "My Album"
      ["Genre"]=>
      string(8) "My Genre"
      ["Kind"]=>
      string(15) "MPEG audio file"
      ["Size"]=>
      int(123456)
      ["Total Time"]=>
      int(123456)
      ["Track Number"]=>
      int(1)
      ["Year"]=>
      int(2008)
      ["Date Modified"]=>
      string(20) "2008-03-03T03:33:33Z"
      ["Date Added"]=>
      string(20) "2008-03-03T03:33:33Z"
      ["Bit Rate"]=>
      int(128)
      ["Sample Rate"]=>
      int(44100)
      ["Comments"]=>
      string(20) "All Rights Reserved."
      ["Release Date"]=>
      string(20) "2007-03-12T04:01:37Z"
      ["Persistent ID"]=>
      string(14) "C3E339393939E3"
      ["Track Type"]=>
      string(4) "File"
      ["Podcast"]=>
      bool(false)
      ["Unplayed"]=>
      bool(true)
      ["File Type"]=>
      int(123456)
      ["File Creator"]=>
      int(123456)
      ["Location"]=>
      string(66) "file://localhost/Users/testUser/Music/iTunes/iTunes%20Music/my.mp3"
      ["File Folder Count"]=>
      int(4)
      ["Library Folder Count"]=>
      int(1)
    }
  }
}

As you can see, the PHP parser made short order of that task. From here you now have full access to all the metadata in your iTunes library. Feel free to use the class in your own projects and be sure to let me know what you build with it.

First off, we need the Enum base class as follows:

abstract class Enum {
	final public function __toString() {
		return get_class($this);
	}
}

From that miniscule amount of code we have the beginnings of Enum support simply by extending that class as follows:

abstract class DNSRecordType extends Enum {}

class A extends DNSRecordType {}
class CNAME extends DNSRecordType {}
class MX extends DNSRecordType {}

function printDnsRecord(DNSRecordType $type, ...) {
       // We can now be sure $type is a DNSRecordType
}

There are of course a few issues, one of the biggest being that (new A) !== (new A) in the above example code. Here we modify the Enum base class to add support for fixing the equality comparison:

abstract class Enum {
	protected static $instances = array();

	final private function __construct() {}

	final public function __toString() {
		return get_class($this);
	}

	final public static function get($name) {
		if(is_subclass_of($name, "Enum")) {
			if(array_key_exists($name, self::$instances)) {
				return self::$instances[$name];
			} else {
				return self::$instances[$name] = new $name();
			}
		} else {
			throw Exception();
		}
	}

	final public static function __callStatic($name, $args) {
		return self::get($name);
	}
}

Now if we want to use an enum, instead of instantiating the CNAME class directly, we use DNSRecordType::get("CNAME"); on versions of PHP older than 5.3 and in PHP 5.3 we can save a few keystrokes and instead use DNSRecordType::CNAME() to get a CNAME. Obviously in the case of older versions of PHP we are adding a few extra keystrokes, but unfortunately that is required to avoid having to define custom methods for each Enum type due to the lack of the __callStatic() magic method before PHP 5.3.

Ok, so what’s next? Well, I guess our next issue would be that Enums, in the case of languages based on C style semantics, by default don’t have the value of a member as the the name of the member, but rather an integer which increments from zero for each member. Furthermore, in C style enums you can set the value too if you like to any integer of your choice and then each member after that which doesn’t have a specified value will be incremented one higher from it consecutively. To support this style behavior, it forces us partly out of being able to do this at compile time (thus a performance hit). Because of the performance hit, I decided you have to enable this mode before using it, otherwise you get the previous behavior we defined above.

The now updated code is as follows:

abstract class Enum {
	protected static $instances = array();
	protected $value = null;

	protected static $pureMode = false;
	protected static $classesWalked = false;
	protected static $typeCounters = array();
	protected static $classIntValues = array();

	final private function __construct() {}

	final public static function enablePureMode() {
		self::$pureMode = true;
	}

	final protected static function walkClasses() {
		if(self::$pureMode && !self::$classesWalked) {
			foreach(get_declared_classes() as $class) {
				if(is_subclass_of($class, "Enum") && $class !== "Enum") {
					$parent = get_parent_class($class);
					if($parent == "Enum") continue;
					if(!array_key_exists($parent, self::$typeCounters)) {
						self::$typeCounters[$parent] = 0;
					}
					$obj = new $class;
					$objval = $obj->value;
					if(!is_null($objval)) {
						if(!is_numeric($objval)) {
							$nextval = ord($objval) + 1;
						} else {
							$nextval = $objval + 1;
						}
						if($nextval <= self::$typeCounters[$parent]) {
							throw new Exception("Specified enum member value is impossible");
						}
						self::$classIntValues[$class] = $objval;
						self::$typeCounters[$parent] = $nextval;
					} else {
						self::$classIntValues[$class] = self::$typeCounters[$parent]++;
					}
				}
			}
			self::$classesWalked = true;
		}
	}

	final public function __toString() {
		if(self::$pureMode) {
			// delay the performance hit until we actually need the value of one of the enums
			self::walkClasses();
			return (string) self::$classIntValues[get_class($this)];
		} else {
			return get_class($this);
		}
	}

	final public static function get($name) {
		if(is_subclass_of($name, "Enum")) {
			if(array_key_exists($name, self::$instances)) {
				return self::$instances[$name];
			} else {
				return self::$instances[$name] = new $name();
			}
		} else {
			throw new Exception();
		}
	}

	final public static function __callStatic($name, $args) {
		return self::get($name);
	}
}

With the above change, we can now have an enums for months with January's value being 1 for example, like the following:

Enum::enablePureMode();
abstract class Month extends Enum {}
class JAN extends Month { var $value = 1; }
class FEB extends Month {}
class MAR extends Month {}
... etc

We can also do things like the following too:

Enum::enablePureMode();
abstract class Whitespace extends Enum {}
class Newline extends Whitespace { var $value = "\n"; }
class Space extends Whitespace { var $value = " "; }
class Tab extends Whitespace { var $value = "\t"; }
... etc

Pretty nifty eh? Please do note, once you enablePureMode it's enabled for all instances of any Enum because you have already incurred the performance loss. Also, due to the nature of how enablePureMode works, you need to make sure you always have all your Enums defined before you try to use one of their values. This shouldn't be an issue in most cases, but just something to keep in mind. Doing quick tests showed the performance hit from having enablePureMode turned on was pretty trivial (less than a millisecond in some cases), but since you might not need the behavior, no point in taking the performance hit if you don't need to.

The last thing left is to make an iterator of all the members of an Enum. This part is really quick and easy and requires us to add the following method to our Enum class:

final public static function iterator($enum_type) {
	return new EnumIterator($enum_type);
}

As well as also define the following additional class:

class EnumIterator implements Iterator {
	protected $classes = array();
	protected $enum_type;

	public function __construct($enum_type) {
		if(!class_exists($enum_type) || !is_subclass_of($enum_type, "Enum")) throw new Exception("Specified Enum type doesn't exist or is not an Enum!");
		$this->enum_type = $enum_type;
		foreach(get_declared_classes() as $class) {
			if(is_subclass_of($class, $this->enum_type)) {
				$this->classes[] = $class;
			}
		}
	}

	public function current() {
		return current($this->classes);
	}

	public function key() {
		return key($this->classes);
	}

	public function next() {
		next($this->classes);
		return $this->current();
	}

	public function rewind() {
		return reset($this->classes);
	}

	public function valid() {
		return (bool) $this->current();
	}
}

An example of using the iterator is as follows:

echo "DNSRecordType:\n";
foreach(Enum::iterator("DNSRecordType") as $type) {
	echo "\t" . $type . " has value " . (Enum::get($type)) . "\n";
}

To get a copy of the code including several example usage demonstrations, please visit the following URL: http://github.com/jsjohnst/php_class_lib/tree/master/classes/types/enum

If you find this useful, please let me know!

-Jeremy