Magic Methods

Magic methods are special methods which override PHP's default's action when certain actions are performed on an object.

Attenzione

All methods names starting with __ are reserved by PHP. Therefore, it is not recommended to use such method names unless overriding PHP's behavior.

The following method names are considered magical: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __serialize(), __unserialize(), __toString(), __invoke(), __set_state(), __clone(), and __debugInfo().

Avviso

All magic methods, with the exception of __construct(), __destruct(), and __clone(), must be declared as public, otherwise an E_WARNING is emitted. Prior to PHP 8.0.0, no diagnostic was emitted for the magic methods __sleep(), __wakeup(), __serialize(), __unserialize(), and __set_state().

Avviso

If type declarations are used in the definition of a magic method, they must be identical to the signature described in this document. Otherwise, a fatal error is emitted. Prior to PHP 8.0.0, no diagnostic was emitted.

__sleep() and __wakeup()

public __sleep ( ) : array
public __wakeup ( ) : void

serialize() checks if the 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. If the method doesn't return anything then null is serialized and E_NOTICE is issued.

Nota:

It is not possible for __sleep() to return names of private properties in parent classes. Doing this will result in an E_NOTICE level error. Use __serialize() instead.

The intended use of __sleep() is to commit pending data or perform similar cleanup tasks. Also, the function is useful if a very large objects doesn't 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 #1 Sleep and wakeup

<?php
class Connection
{
    protected 
$link;
    private 
$dsn$username$password;
    
    public function 
__construct($dsn$username$password)
    {
        
$this->dsn $dsn;
        
$this->username $username;
        
$this->password $password;
        
$this->connect();
    }
    
    private function 
connect()
    {
        
$this->link = new PDO($this->dsn$this->username$this->password);
    }
    
    public function 
__sleep()
    {
        return array(
'dsn''username''password');
    }
    
    public function 
__wakeup()
    {
        
$this->connect();
    }
}
?>

__serialize() and __unserialize()

public __serialize ( ) : array
public __unserialize ( array $data ) : void

serialize() checks if the class has a function with the magic name __serialize(). If so, that function is executed prior to any serialization. It must construct and return an associative array of key/value pairs that represent the serialized form of the object. If no array is returned a TypeError will be thrown.

Nota:

If both __serialize() and __sleep() are defined in the same object, only __serialize() will be called. __sleep() will be ignored. If the object implements the Serializable interface, the interface's serialize() method will be ignored and __serialize() used instead.

The intended use of __serialize() is to define a serialization-friendly arbitrary representation of the object. Elements of the array may correspond to properties of the object but that is not required.

Conversely, unserialize() checks for the presence of a function with the magic name __unserialize(). If present, this function will be passed the restored array that was returned from __serialize(). It may then restore the properties of the object from that array as appropriate.

Nota:

If both __unserialize() and __wakeup() are defined in the same object, only __unserialize() will be called. __wakeup() will be ignored.

Nota:

This feature is available as of PHP 7.4.0.

Example #2 Serialize and unserialize

<?php
class Connection
{
    protected 
$link;
    private 
$dsn$username$password;

    public function 
__construct($dsn$username$password)
    {
        
$this->dsn $dsn;
        
$this->username $username;
        
$this->password $password;
        
$this->connect();
    }

    private function 
connect()
    {
        
$this->link = new PDO($this->dsn$this->username$this->password);
    }

    public function 
__serialize(): array
    {
        return [
          
'dsn' => $this->dsn,
          
'user' => $this->username,
          
'pass' => $this->password,
        ];
    }

    public function 
__unserialize(array $data): void
    
{
        
$this->dsn $data['dsn'];
        
$this->username $data['user'];
        
$this->password $data['pass'];

        
$this->connect();
    }
}
?>

__toString()

public __toString ( ) : string

The __toString() method allows a class to decide how it will react when it is treated like a string. For example, what echo $obj; will print.

Avviso

As of PHP 8.0.0, the return value follows standard PHP type semantics, meaning it will be coerced into a string if possible and if strict typing is disabled.

In PHP 7.4, the returned value must be a string, otherwise an Error is thrown.

Prior to PHP 7.4.0, the returned value must be a string, otherwise a fatal E_RECOVERABLE_ERROR is emitted.

Avviso

It was not possible to throw an exception from within a __toString() method prior to PHP 7.4.0. Doing so will result in a fatal error.

Example #3 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;
?>

Il precedente esempio visualizzerà:

Hello

__invoke()

__invoke ( ...$values ) : mixed

The __invoke() method is called when a script tries to call an object as a function.

Example #4 Using __invoke()

<?php
class CallableClass
{
    public function 
__invoke($x)
    {
        
var_dump($x);
    }
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>

Il precedente esempio visualizzerà:

int(5)
bool(true)

__set_state()

static __set_state ( array $properties ) : object

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

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

Example #5 Using __set_state()

<?php

class A
{
    public 
$var1;
    public 
$var2;

    public static function 
__set_state($an_array)
    {
        
$obj = new A;
        
$obj->var1 $an_array['var1'];
        
$obj->var2 $an_array['var2'];
        return 
$obj;
    }
}

$a = new A;
$a->var1 5;
$a->var2 'foo';

$b var_export($atrue);
var_dump($b);
eval(
'$c = ' $b ';');
var_dump($c);
?>

Il precedente esempio visualizzerà:

string(60) "A::__set_state(array(
   'var1' => 5,
   'var2' => 'foo',
))"
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

Nota: When exporting an object, var_export() does not check whether __set_state() is implemented by the object's class, so re-importing such objects will fail, if __set_state() is not implemented. Particularly, this affects some internal classes. It is the responsibility of the programmer to verify that only objects will be re-imported, whose class implements __set_state().

__debugInfo()

__debugInfo ( ) : array

This method is called by var_dump() when dumping an object to get the properties that should be shown. If the method isn't defined on an object, then all public, protected and private properties will be shown.

Example #6 Using __debugInfo()

<?php
class {
    private 
$prop;

    public function 
__construct($val) {
        
$this->prop $val;
    }

    public function 
__debugInfo() {
        return [
            
'propSquared' => $this->prop ** 2,
        ];
    }
}

var_dump(new C(42));
?>

Il precedente esempio visualizzerà:

object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}
add a note add a note

User Contributed Notes 46 notes

up
33
jon at webignition dot net
12 years ago
The __toString() method is extremely useful for converting class attribute names and values into common string representations of data (of which there are many choices). I mention this as previous references to __toString() refer only to debugging uses.

I have previously used the __toString() method in the following ways:

- representing a data-holding object as:
   - XML
   - raw POST data
   - a GET query string
   - header name:value pairs

- representing a custom mail object as an actual email (headers then body, all correctly represented)

When creating a class, consider what possible standard string representations are available and, of those, which would be the most relevant with respect to the purpose of the class.

Being able to represent data-holding objects in standardised string forms makes it much easier for your internal representations of data to be shared in an interoperable way with other applications.
up
6
kguest at php dot net
3 years ago
__debugInfo  is also utilised when calling print_r on an object:

$ cat test.php
<?php
class FooQ {

     private
$bar = '';

     public function
__construct($val) {

        
$this->bar = $val;
     }

     public function
__debugInfo()
     {
         return [
'_bar' => $this->bar];
     }
}
$fooq = new FooQ("q");
print_r ($fooq);

$
php test.php
FooQ Object
(
    [
_bar] => q
)
$
up
9
jsnell at e-normous dot com
12 years ago
Be very careful to define __set_state() in classes which inherit from a parent using it, as the static __set_state() call will be called for any children.  If you are not careful, you will end up with an object of the wrong type.  Here is an example:

<?php
class A
{
    public
$var1;

    public static function
__set_state($an_array)
    {
       
$obj = new A;
       
$obj->var1 = $an_array['var1']; 
        return
$obj;
    }
}

class
B extends A {
}

$b = new B;
$b->var1 = 5;

eval(
'$new_b = ' . var_export($b, true) . ';');
var_dump($new_b);
/*
object(A)#2 (1) {
  ["var1"]=>
  int(5)
}
*/
?>
up
1
daniel dot peder at gmail dot com
2 years ago
http://sandbox.onlinephpfunctions.com/code/4d2cc3648aed58c0dad90c7868173a4775e5ba0c

IMHO a bug or need feature change

providing a object as a array index doesn't try to us __toString() method so some volatile object identifier is used to index the array, which is breaking any persistency. Type hinting solves that, but while other than "string" type hinting doesn't work on ob jects, the automatic conversion to string should be very intuitive.

PS: tried to submit bug, but withot patch the bugs are ignored, unfortunately, I don't C coding

<?php

class shop_product_id {
   
    protected
$shop_name;
    protected
$product_id;
   
    function
__construct($shop_name,$product_id){
       
$this->shop_name = $shop_name;
       
$this->product_id = $product_id;
    }

    function
__toString(){
        return
$this->shop_name . ':' . $this->product_id;
    }
}

$shop_name = 'Shop_A';
$product_id = 123;
$demo_id = $shop_name . ':' . $product_id;
$demo_name = 'Some product in shop A';

$all_products = [ $demo_id => $demo_name ];
$pid = new shop_product_id( $shop_name, $product_id );

echo
"with type hinting: ";
echo (
$demo_name === $all_products[(string)$pid]) ? "ok" : "fail";
echo
"\n";

echo
"without type hinting: ";
echo (
$demo_name === $all_products[$pid]) ?  "ok" : "fail";
echo
"\n";
up
8
daan dot broekhof at gmail dot com
9 years ago
Ever wondered why you can't throw exceptions from __toString()? Yeah me too.

Well now you can! This trick allows you to throw any type of exception from within a __toString(), with a full & correct backtrace.

How does it work? Well PHP __toString() handling is not as strict in every case: throwing an Exception from __toString() triggers a fatal E_ERROR, but returning a non-string value from a __toString() triggers a non-fatal E_RECOVERABLE_ERROR.
Add a little bookkeeping, and can circumvented this PHP deficiency!
(tested to work PHP 5.3+)

<?php

set_error_handler
(array('My_ToStringFixer', 'errorHandler'));
error_reporting(E_ALL | E_STRICT);

class
My_ToStringFixer
{
    protected static
$_toStringException;

    public static function
errorHandler($errorNumber, $errorMessage, $errorFile, $errorLine)
    {
        if (isset(
self::$_toStringException))
        {
           
$exception = self::$_toStringException;
           
// Always unset '_toStringException', we don't want a straggler to be found later if something came between the setting and the error
           
self::$_toStringException = null;
            if (
preg_match('~^Method .*::__toString\(\) must return a string value$~', $errorMessage))
                throw
$exception;
        }
        return
false;
    }
   
    public static function
throwToStringException($exception)
    {
       
// Should not occur with prescribed usage, but in case of recursion: clean out exception, return a valid string, and weep
       
if (isset(self::$_toStringException))
        {
           
self::$_toStringException = null;
            return
'';
        }

       
self::$_toStringException = $exception;

        return
null;
    }
}

class
My_Class
{
    public function
doComplexStuff()
    {
        throw new
Exception('Oh noes!');
    }

    public function
__toString()
    {
        try
        {
           
// do your complex thing which might trigger an exception
           
return $this->doComplexStuff();
        }
        catch (
Exception $e)
        {
           
// The 'return' is required to trigger the trick
           
return My_ToStringFixer::throwToStringException($e);
        }
    }
}

$x = new My_Class();

try
{
    echo
$x;
}
catch (
Exception $e)
{
    echo
'Caught Exception! : '. $e;
}
?>
up
5
dhuseby domain getback tld com
13 years ago
The above hint for using array_keys((array)$obj) got me investigating how to get __sleep to really work with object hierarchies.

With PHP 5.2.3, If you want to serialize an object that is part of an object hierarchy and you want to selectively serialize members (public, private, and protected) by manually specifying the array of members, there are a few simple rules for naming members that you must follow:

1. public members should be named using just their member name, like so:

<?php
class Foo {
    public
$bar;

    public function
__sleep() {
        return array(
"bar");
    }
}
?>

2. protected members should be named using "\0" . "*" . "\0" . member name, like so:

<?php
class Foo {
    protected
$bar;

    public function
__sleep() {
        return array(
"\0*\0bar");
    }
}
?>

3. private members should be named using "\0" . class name . "\0" . member name, like so:

<?php
class Foo {
    private
$bar;

    public function
__sleep() {
        return array(
"\0Foo\0bar");
    }
}
?>

So with this information let us serialize a class hierarchy correctly:

<?php

class Base {
    private
$foo = "foo_value";
    protected
$bar = "bar_value";

    public function
__sleep() {
        return array(
"\0Base\0foo", "\0*\0bar");
    }
}

class
Derived extends Base {
    public
$baz = "baz_value";
    private
$boo = "boo_value";

    public function
__sleep() {
       
// we have to merge our members with our parent's
       
return array_merge(array("baz", "\0Derived\0boo"), parent::__sleep());
    }
}

class
Leaf extends Derived {
    private
$qux = "qux_value";
    protected
$zaz = "zaz_value";
    public
$blah = "blah_value";

    public function
__sleep() {
       
// again, merge our members with our parent's
       
return array_merge(array("\0Leaf\0qux", "\0*\0zaz", "blah"), parent::__sleep());
    }
}

// test it
$test = new Leaf();
$s = serialize($test);
$test2 = unserialize($s);
echo
$s;
print_r($test);
print_r($test2);

?>

Now if you comment out all of the __sleep() functions and output the serialized string, you will see that the output doesn't change.  The most important part of course is that with the proper __sleep() functions, we can unserialize the string and get a properly set up object.

I hope this solves the mystery for everybody.  __sleep() does work, if you use it correctly :-)
up
1
smiley at HELLOSPAMBOT dot chillerlan dot net
5 years ago
A simple API wrapper, using __call() and the PHP 5.6 "..." token.
http://php.net/manual/functions.arguments.php#functions.variable-arg-list

<?php
namespace Example;

use
Exception;
use
ReflectionClass;
use
SomeApiInterface;
use
SomeHttpClient;
use
SomeEndpointHandler;

/**
* Class SomeApiWrapper
*
* @method SomeEndpointHandler method1(MethodParams $param1)
* @method SomeEndpointHandler method2(MethodParams $param1, AuthParams $param2 = null)
* ...
* @method SomeEndpointHandler method42()
*/
class SomeApiWrapper{

   
/**
     * @var \SomeHttpClient
     */
   
private $httpClient;

   
/**
     * @var array
     */
   
private $methodMap = [];

   
/**
     * SomeApiWrapper constructor.
     */
   
public function __construct(){
       
$this->mapApiMethods();
       
$this->httpClient = new SomeHttpClient();
    }

   
/**
     * The API is flat and has ~ 150 endpoints, all of which take optional parameters
     * from up to 3 groups (method params, authentication, filters). Instead of
     * implementing the interface and adding countless stubs that have basically
     * the same signature, i just map its methods here and use __call().
     */
   
private function mapApiMethods(){
       
$reflectionClass = new ReflectionClass(SomeApiInterface::class);

        foreach(
$reflectionClass->getMethods() as $m){
           
$this->methodMap[] = $m->name;
        }
    }

   
/**
     * Thanks to the PHP 5.6+ "..." token, there's no hassle with the arguments anymore
     * (ugh, bad pun). Just hand the method parameters into the endpoint handler,
     * along with other mandatory params - type hints are your friends.
     *
     * It's magic!
     *
     * @param string $method
     * @param array  $arguments
     *
     * @return \SomeEndpointHandler
     * @throws \Exception
     */
   
public function __call($method, $arguments){

        if(
in_array($method, $this->methodMap)){
            return new
SomeEndpointHandler($this->httpClient, $method, ...$arguments);
        }

        throw new
Exception('Endpoint "'.$method.'" does not exist');
    }

}
up
1
Anonymous
12 years ago
Serializing objects is problematic with references. This is solved redefining the __sleep() magic method. This is also problematic when parent class has private variables since the parent object is not accessible nor its private variables from within the child object.

I found a solution that seems working for classes that implements this __sleep() method, and for its subclasses. Without more work in subclasses. The inheritance system does the trick.

Recursively __sleep() call parent' __sleep() and return the whole array of variables of the object instance to be serialized.

<?php
class foo {
}

class
a {
  private
$var1;

  function
__construct(foo &$obj = NULL) {
   
$this->var1 = &$obj;
  }

 
/** Return its variables array, if its parent exists and the __sleep method is accessible, call it and push the result into the array and return the whole thing. */
 
public function __sleep() {
   
$a = array_keys(get_object_vars(&$this));
    if (
method_exists(parent, '__sleep')) {
     
$p = parent::__sleep();
     
array_push($a, $p);
    };
    return
$a;
  }
}

class
b extends a {
  function
__construct(foo &$obj = NULL) {
   
parent::__construct($obj);
  }
}

session_start();
$myfoo = &new foo();
$myb = &new b($myfoo);
$myb = unserialize(serialize(&$myb));
?>

This should work, I haven't tested deeper.