Magic Methods

The function names __construct, __destruct (see Constructors and Destructors), __call, __get, __set, __isset, __unset (see Overloading), __sleep, __wakeup, __toString, __set_state, __clone and __autoload are magical in PHP classes. You cannot have functions with these names in any of your classes unless you want the magic functionality associated with them.

Caution

PHP reserves all function names starting with __ as magical. It is recommended that you do not use function names with __ in PHP unless you want some documented magic functionality.

__sleep and __wakeup

serialize() checks if your class has a function with the magic name __sleep. If so, that function is executed prior to any serialization. It can clean up the object and is supposed to return an array with the names of all variables of that object that should be serialized.

The intended use of __sleep is to close any database connections that the object may have, commit pending data or perform similar cleanup tasks. Also, the function is useful if you have very large objects which do not need to be saved completely.

Conversely, unserialize() checks for the presence of a function with the magic name __wakeup. If present, this function can reconstruct any resources that the object may have.

The intended use of __wakeup is to reestablish any database connections that may have been lost during serialization and perform other reinitialization tasks.

Example 19-26. Sleep and wakeup

<?php
class Connection {
    
protected $link;
    
private $server, $username, $password, $db;
    
    
public function __construct($server, $username, $password, $db)
    {
        
$this->server = $server;
        
$this->username = $username;
        
$this->password = $password;
        
$this->db = $db;
        
$this->connect();
    }
    
    
private function connect()
    {
        
$this->link = mysql_connect($this->server, $this->username, $this->password);
        
mysql_select_db($this->db, $this->link);
    }
    
    
public function __sleep()
    {
        
mysql_close($this->link);
    }
    
    
public function __wakeup()
    {
        
$this->connect();
    }
}
?>

__toString

The __toString method allows a class to decide how it will react when it is converted to a string.

Example 19-27. Simple example

<?php
// Declare a simple class
class TestClass
{
    
public $foo;

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

    
public function __toString() {
        return
$this->foo;
    }
}

$class = new TestClass('Hello');
echo
$class;
?>

The above example will output:

Hello

It is worth noting that the __toString method will only be called when it is directly combined with echo() or print().

Example 19-28. Cases where __toString is called

<?php
// __toString called
echo $class;

// __toString called (still a normal parameter for echo)
echo 'text', $class;

// __toString not called (concatenation operator used first)
echo 'text' . $class;

// __toString not called (cast to string first)
echo (string) $class;

// __toString not called (cast to string first)
echo "text $class";
?>

__set_state

This static method is called for classes exported by var_export() since PHP 5.1.0.

The only parameter of this method is an array containing exported properties in the form array('property' => value, ...).