Serialization (Programming PHP)

6.6. Serialization

Serializing an object means converting it to a bytestream representation that can be stored in a file. This is useful for persistent data; for example, PHP sessions automatically save and restore objects. Serialization in PHP is mostly automatic—it requires little extra work from you, beyond calling the serialize( ) and unserialize( ) functions:

$encoded = serialize(something);
$something = unserialize(encoded);

Serialization is most commonly used with PHP's sessions, which handle the serialization for you. All you need to do is tell PHP which variables to keep track of, and they're automatically preserved between visits to pages on your site. However, sessions are not the only use of serialization—if you want to implement your own form of persistent objects, the serialize( ) and unserialize( ) functions are a natural choice.

An object's class must be defined before unserialization can occur. Attempting to unserialize an object whose class is not yet defined puts the object into stdClass, which renders it almost useless. One practical consequence of this is that if you use PHP sessions to automatically serialize and unserialize objects, you must include the file containing the object's class definition in every page on your site. For example, your pages might start like this:

<?php 
 include('object_definitions.inc');  // load object definitions
 session_start( );                    // load persistent variables
?>
<html>...

PHP has two hooks for objects during the serialization and unserialization process: _ _sleep( ) and _ _wakeup( ). These methods are used to notify objects that they're being serialized or unserialized. Objects can be serialized if they do not have these methods; however, they won't be notified about the process.

The _ _sleep( ) method is called on an object just before serialization; it can perform any cleanup necessary to preserve the object's state, such as closing database connections, writing out unsaved persistent data, and so on. It should return an array containing the names of the data members that need be written into the bytestream. If you return an empty array, no data is written.

Conversely, the _ _wakeup( ) method is called on an object immediately after an object is created from a bytestream. The method can take any action it requires, such as reopening database connections and other initialization tasks.

Example 6-3 is an object class, Log, which provides two useful methods: write( ) to append a message to the logfile, and read( ) to fetch the current contents of the logfile. It uses _ _wakeup( ) to reopen the logfile and _ _sleep( ) to close the logfile.

Example 6-3. The Log.inc file

<?php
 class Log {
   var $filename;
   var $fp;

   function Log($filename) {
     $this->filename = $filename;
     $this->open( );
   }

   function open( ) {
     $this->fp = fopen($this->filename, "a")
                 or die("Can't open {$this->filename}");
   }

   function write($note) {
     fwrite($this->fp, "$note\n");
   }

   function read( ) {
     return join('', file($this->filename));
   }

   function _  _wakeup( ) {
     $this->open( );
   }

   function _  _sleep( ) {
     // write information to the account file
     fclose($this->fp);
     return array('filename');
   }
 }
?>

Store the Log class definition in a file called Log.inc. The HTML page in Example 6-4 uses the Log class and PHP sessions to create a persistent log variable, $l.

Example 6-4. front.php

<?php
 include_once('Log.inc');
 session_start( );
?>

<html><head><title>Front Page</title></head>
<body>

<?php
 $now = strftime("%c");

 if (!session_is_registered('l')) {
   $l = new Log("/tmp/persistent_log");
   session_register('l');
   $l->write("Created $now");
   echo("Created session and persistent log object.<p>");
 }

 $l->write("Viewed first page $now");
 echo "The log contains:<p>";
 echo nl2br($l->read( ));
?>

<a href="next.php">Move to the next page</a>

</body></html>

The output when this page is viewed is shown in Figure 6-3.

Figure 6-3. The front page

Example 6-5 shows the file next.php, an HTML page. Following the link from the front page to this page triggers the loading of the persistent object $l. The _ _wakeup( ) call reopens the logfile so that the object is ready to be used.

Example 6-5. next.php

<?php
 include_once('Log.inc');
 session_start( );
?>

<html><head><title>Next Page</title></head>
<body>

<?php
 $now = strftime("%c");
 $l->write("Viewed page 2 at $now");

 echo "The log contains:<p>";
 echo nl2br($l->read( ));
?>

</body></html>

Figure 6-4 shows the output of next.php.

Figure 6-4. The next page