PHP provides a number of 'magic' methods that allow you to do some pretty neat tricks in object oriented programming. These methods, identified by a two underscore prefix (__), function as interceptors that are automatically called when certain conditions are met. Magic methods provide some extremely useful functionality, and this tutorial will demonstrate each method's use.

Before We Begin

In order to fully understand magic methods, it's helpful to see them in action. So let's start with a base set of very simple classes. Here we define two classes: Device and Battery.

If words like "method" and "property" sound alien to you, you might want to read up on this first.

Device objects will hold a name, a Battery object, an array of data, and a handle to some external resource. They also have methods for connecting and disconnecting the external resource. Battery objects simply store a charge in a private property and have a method to set the charge.

This tutorial assumes you have a basic understanding of object oriented programming. If words like "method" and "property" sound alien to you, you might want to read up on that first.

These classes are pretty useless, but they make a good example for each of the magic methods. So now that we have our simple classes created, we can try out the magic methods.

Constructors & Destructors

Constructors and destructors are called when an object is created and destroyed, respectively. An object is "destroyed" when there are no more references to it, either because the variable holding it was unset/reassigned or the script ended execution.

__construct()

The __construct() method is by far the most commonly used magic method. This is where you do any initialization you need when an object is created. You can define any number of arguments here, which will be passed when creating objects. Any return value will be passed through the new keyword. Any exceptions thrown in the constructor will halt object creation.

Declaring the constructor method 'private' prevents external code from directly creating an object.

Here we have declared a constructor that accepts two arguments, a Battery and a name. The constructor assigns each of the properties that the objects requires to function and runs the connect() method. The constructor allows you to ensure that an object has all the required pieces before it can exist.

Tip: Declaring the constructor method 'private' prevents external code from directly creating an object. This is handy for creating singleton classes that restrict the number of objects that can exist.

With the above constructor in place, here is how you create a Device called 'iMagic':

As you can see, arguments passed to the class are actually being passed to the constructor method. You can also tell that the connect method was called and the $name property was populated.

Let's say we forget to pass a name. Here's what happens:

__destruct()

As the name implies, the __destruct() method is called when the object is destroyed. It accepts no arguments and is commonly used to perform any cleanup operations such as closing a database connection. In our case, we'll use it to disconnect from the network.

With the above destructor in place, here is what happens when a Device object is destroyed:

Here, we've destroyed the object using unset() . Before it is destroyed, the destructor calls the disconnect() method and prints a message, which you can see in the comments.

Property Overloading

Note: PHP's version of "overloading" is not quite the same as most other languages, though the same results can be reached.

This next set of magic methods are about dealing with property access, defining what happens when you try to access a property that does not exist (or is not accessible). They can be used to create pseudo properties. This is called overloading in PHP.

__get()

The __get() method is called when code attempts to access a property that is not accessible. It accepts one argument, which is the name of the property. It should return a value, which will be treated as the value of the property. Remember the $data property in our Device class? We'll be storing these "pseudo properties" as elements in the data array, and we can let users of our class access them via __get() . Here's what it looks like:

A popular use of the __get() method is to extend the access control by creating "read-only" properties. Take our Battery class, for example, which has a private property. We can allow the private $charge property to be read from outside code, but not changed. The code would look like this:

In this example, note the use of variable variables to dynamically access a property. Assuming the value 'user' for $name , $this->$name translates to $this->user .

__set()

The __set() method is called when code attempts to change the value a property that is not accessible. It accepts two arguments, which are the name of the property and the value. Here's what that looks like for the "pseudo variables" array in our Device class:

__isset()

The __isset() method is called when code calls isset() on a property that is not accessible. It accepts one argument, which is the name of the property. It should return a Boolean value representing the existence of a value. Again using our variable array, here's what that looks like:

__unset()

The __unset() method is called when code attempts to unset() a property that is not accessible. It accepts one argument, which is the name of the property. Here's what ours looks like:

Property Overloading in Action

Here are all of the property related magic methods we have declared:

With the above magic methods, here is what happens when we try to access a property called name. Remember that there isn't really a $name property declared, though you'd never know that without seeing the internal class code.

We have set and successfully retrieved the value of a nonexistent property. Well where is it stored then?

As you can see, the $data property now contains a 'name' element with our value.

Above is the result of calling isset() on the fake property.

Above is the result of unsetting the fake property. Just to make sure, here is our empty data array:

Representing Objects As Text

Sometimes you might want to convert an object to a string representation. If you simply try to print an object we'll get an error, such as the one below:

__toString()

The __toString() method is called when code attempts to treat an object like a string. It accepts no arguments and should return a string. This allows us to define how the object will be represented. In our example, we'll create a simple summary:

With the above method defined, here is what happens when we try to print a Device object:

The Device object is now represented by a short summary containing the name, status, and number of stored items.

__set_state() (PHP 5.1)

The static __set_state() method (available as of PHP version 5.1) is called when the var_export() function is called on our object. The var_export() function is used to convert a variable to PHP code. This method accepts an associative array containing the property values of the object. For simplicity's sake, well use it in our Battery class.

Our method simply creates an instance of its parent class and sets to charge to the value in the passed array. With the above method defined, here is what happens when we use var_export() on a Device object:

The first comment shows what is actually happening, which is that var_export() simply calls Battery::__set_state() . The second comment shows us successfully recreating the Battery.

Cloning Objects

Objects, by default, are passed around by reference. So assigning other variables to an object will not actually copy the object, it will simply create a new reference to the same object. In order to truly copy an object, we must use the clone keyword.

This 'pass by reference' policy also applies to objects within objects. Even if we clone an object, any child objects it happens to contain will not be cloned. So we would end up with two objects that share the same child object. Here's an example that illustrates that:

Here, we have cloned a Device object. Remember that all Device objects contain a Battery object. To demonstrate that both clones of the Device share the same Battery, the change we made to $device's Battery is reflected in $device2's Battery.

__clone()

The __clone() method can be used to solve this problem. It is called on the copy of a cloned object after cloning takes place. This is where you can clone any child objects.

With this method declared, we can now be sure the cloned Devices each have their own Battery.

Changes to one Device's Battery do not affect the other.

Object Serialization

Serialization is the process that converts any data into a string format. This can be used to store entire objects into a file or database. When you unserialize the stored data, you'll have the original object exactly as it was before. One problem with serialization, though, is that not everything can be serialized, such as database connections. Fortunately there are some magic methods that allow us to handle this problem.

__sleep()

The __sleep() method is called when the serialize() function is called on the object. It accepts no arguments and should return an array of all properties that should be serialized. You can also complete any pending tasks or cleanup that may be necessary in this method.

Tip: Avoid doing anything destructive in __sleep() since this will affect the live object, and you may not always be done with it.

In our Device example, the connection property represents an external resource that cannot be serialized. So our __sleep() method simply returns an array of all the properties except $connection .

Our __sleep() simply returns a list of the names of properties that should be preserved.

__wakeup()

The __wakeup() method is called when the unserialize() function is called on the stored object. It accepts no arguments and does not need to return anything. Use it to reestablish any database connection or resource that was lost in serialization.

In our Device example, we simply need to reestablish our connection by calling our connect() method.

Method Overloading

These last two methods are for dealing with methods. This is the same concept as the property overloading methods ( __get() , __set() , etc), but applied to methods.

__call()

The __call() is called when code attempts to call inaccessible or nonexistent methods. It accepts two arguments: the name of the called method and an array of arguments. You can use this information to call the same method in a child object, for example.

In the examples, note the use of the call_user_func_array() function. This function allows us to dynamically call a named function (or method) with the arguments stored in an array. The first argument identifies the function to call. In the case of naming methods, the first argument is an array containing a class name or object instance and the name of the property. The second argument is always an indexed array of arguments to pass.

In our example, we'll be passing the method call to our $connection property (which we assume is an object). We'll return the result of that straight back to the calling code.

The above method would be called if we try to call the iDontExist() method:

__callStatic() (PHP 5.3)

The __callStatic() (available as of PHP version 5.3) is identical to __call() except that it is called when code attempts to call inaccessible or nonexistent methods in a static context.

The only differences in our example is that we declare the method as static and we reference a class name instead of an object.

The above method would be called if we try to call the static iDontExist() method:

Using Objects As Functions

Sometimes you might want to use an object as a function. Being able to use an object as a function allows you to pass functions around as arguments like you can in other languages.

__invoke() (PHP 5.3)

The __invoke() (available as of PHP version 5.3) is called when code tries to use the object as a function. Any arguments defined in this method will be used as the function arguments. In our example, we'll simply be printing the argument that it receives.

With the above defined, this is what happens when we use a Device as a function:

Bonus: __autoload()

This is not a magic method, but it is still very useful. The __autoload() function is automatically called when a class that doesn't exist is referenced. It is meant to give you one last chance to load the file containing the class declaration before your script fails. This is useful since you don't always want to load every class just in case you need it.

The function accepts one argument: the name of the referenced class. Say you have each class in a file named 'classname.class.php' in the 'inc' directory. Here is what your autoload would look like:

Conclusion

Magic methods are extremely useful and provide powerful tools for developing flexible application frameworks. They bring PHP objects closer to those in other object oriented languages by allowing you to reproduce some of their more useful features. You can read the PHP manual pages on magic methods here. I hope this tutorial was helpful and clearly explained the concepts. If you have any questions, don't hesitate to ask in the comments. Thanks for reading.