An experienced PHP developer might be wondering why posting this topic in a blog if PHP already has universal and almost transparent tools for this job, specifically serialize and unserialize built-in functions.

The key statement here is “almost transparent” which means you have to include all class definitions before invoking unserialize or use some __autoload schema. Otherwise you are going to face the dreaded “The script tried to execute a method or access a property of an incomplete object” fatal error.

The whole problem is due to the fact a serialized object has no idea about its class definition except the class name(the reason behind that is absolutely valid).

To illustrate this problem have a look at the following trivial code which echoes serialized version of the Foo class.

<?php
class Foo {
  function say(){
    echo 'Foo';
  }
}

$foo = new Foo();
echo serialize($foo);

If you execute the snippet above it should print the following:

O:3:"Foo":0:{}

Now let’s try unserializing this string in order to experience the “incomplete object” error:

<?php
$str = 'O:3:"Foo":0:{}';
$foo = unserialize($str);
$foo->say();

Try running this code, you should see the following:

“Fatal error: main(): The script tried to execute a method or access a property of an incomplete object. Please ensure that the class definition “Foo” of the object you are trying to operate on was loaded _before_ unserialize() gets called or provide a __autoload() function to load the class definition in….”

Tada

As error message clearly states you should include all classes before unserializing or provide a proper __autoload function. In my opinion none of these options are perfect and universal, here is why:

• If you are using some generic serialization subsystem(e.g. universal cache or session persistence handler) you simply can’t predict what classes you actually need to include. And of course including all of them is very impractical.
• __autoload may be your savior but in this case you need to decide how you are going to map class names to the actual files containing them on the disk:
  • Some folks(e.g. ZendFramework) encode path to the file in a class name using “_” as delimiters(e.g. “My_Db_Mysql_Row”) then simply replace “_” with “/” in __autoload, append “.php” and include the file.
  • Others(e.g. ezComponents IIRC) maintain static autoload maps with keys of such maps being class names and values - PHP file names containing these classes.

  I believe both of these options put quite severe constraints on a developer which is generally a “bad thing”. For example, some developers find __autoload being way too magic and hate encoding a path to a file in a class name.

That’s why I decided to hack up, hopefully, a more universal solution to this problem

The main idea is to use a special serialization container class(SerializableContainer) which would take care of including class definitions automatically. The best way to show how it works is to provide some sample code, serialization first:

<?php
...
$foo = new Foo();
$serializable = new SerializableContainer($foo);
file_put_contents('./data', serialize($serializable));

…and here comes unserialization:

<?php
...
$serializable = unserialize(file_get_contents('./data'));
$foo = $serializable->getSubject();
$foo->say(); //should work just fine

No PHP fatal error is raised because SerializableContainer automagically includes all required class definitions during unserializing process. Before I show its code, here’s how it works step by step:

1. Remember the way serialized object string looks like for $foo object? Here it is once again: O:3:”Foo”:0:{}. The most interesting part of it is the beginning: O:N… which tells to the userialize function we’ve got some object’s data here. Using simple regex it’s possible to extract all class names from the serialized string!
2. Now, provided we have all class names extracted, we should somehow get files where they were included from. It’s a no-brainer using PHP5 reflection capabilities: $reflect = new ReflectionClass($class); $reflect->getFileName();
3. The “class => file” map should be stored in SerializableContainer as an attribute and serialized along with other stuff since we’ll use it for class files inclusion upon unserialization.
4. Finally, on data unserialization all we have to do is just to include required class files.

Ok, here’s the code:

<?php

class SerializableContainer {
  protected $subject;
  protected $serialized;
  protected $class_paths = array();

  function __construct($subject) {
    $this->subject = $subject;
  }

  function getSubject() {
    if($this->serialized) {
      $this->_includeFiles();
      $this->subject = unserialize($this->serialized);
      unset($this->serialized);
    }
    return $this->subject;
  }

  function __sleep() {
    $this->serialized = serialize($this->subject);
    $this->_fillClassPathInfo($this->serialized);
    return array('serialized', 'class_paths');
  }

  function _includeFiles() {
    foreach($this->class_paths as $path)
      require_once($path);
  }

  function _fillClassPathInfo($serialized) {
    $classes = $this->_extractSerializedClasses($serialized);
    $this->class_paths = array();

    foreach($classes as $class) {
      $reflect = new ReflectionClass($class);
      $this->class_paths[] = $reflect->getFileName();
    }
  }

  function _extractSerializedClasses($str) {
    if(preg_match_all('~([||;]O|^O):d+:"([^"]+)":d+:{~', $str, $m))
      return array_unique($m[2]);
    else
      return array();
  }
}

A couple of ideas where SerializableContainer could be quite handy:

a) Some transparent session persistence wrapper

<?php

class Session {
...
  function get($name) {
    if(!isset($_SESSION[$name]))
      return null;

    if(is_object($_SESSION[$name]) && $_SESSION[$name] instanceof SerializableContainer)
      return $_SESSION[$name]->getSubject();
    else
      return $_SESSION[$name];
  }

  function set($name, $value) {
    if(is_object($value)) {
      $serializable = new SerializableContainer($value);
      $_SESSION[$name] = $serializable;
    }
    else
      $_SESSION[$name] = $value;
  }
...
}

b) Some generic file(database, etc) caching subsystem

<?php
class FileCache {
  function set($key, $value, $params = array()) {
    $file = $this->getCacheDir() . '/' . $this->_getCacheFileName($key, $params);
    $container = new SerializableContainer($value);
    file_put_contents($file, serialize($container));
  }

  function get($key, $params = array()) {
    if(!$file = $this->_findCacheFile($key))
      return false;
    $container = unserialize(file_get_contents($file));
    return $container->getSubject();
  }

Well, I think, you get the idea

As everything in our world, SerializableContainer is not perfect:

• It depends on PHP’s internal serialization format. Should PHP core developers ever change it(word on the street, this is possible in PHP6) there’s a big chance SerializableContainer may get broken. Hopefully this can be fixed by adding proper phpversion and version_compare checks into it.
• SerializableContainer uses a regular expression in order to extract class names from the raw serialized data which potentially may become a bottleneck for a large amount of data. I have not profiled it, but, I believe, if that’s the case, the regex can be replaced with a number of faster strpos/substr equivalent calls(or rewritten as a PHP extension in the worst scenario)
• You should think twice before relocating files with classes which were subject to serialization using this approach since you may face “file not found” error(once again, SerializableContainer stores full paths to files containing classes)
• If this approach is used in a cluster, all servers must have all PHP code stored using identical file system layout for obvious reasons.

What do you think about this approach?

P.S. Actually such SerializableContainer is implemented in limb/core package as a lmbSerializable class(here’s a unit test), feel free to use it.

This entry was posted on Monday, December 10th, 2007 at 3:59 am and is filed under oop, php. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.