The __toString() Method – Objects as Strings

This entry is part 1 of 4 in the series Magic Methods in PHP

We started the study of PHP magic methods by learning about __get() magic method. All the names of magic methods are reserved and cannot be used for any other purpose. Moreover, all functions starting with double underscore (__) are reserved for an object in PHP. A very common example of magic methods is constructor and destructor. Both the methods serve the defined purpose and the reserved names cannot be used for any other purpose. The __toString() is another useful magic method in PHP.

PHP is loosely typed language and same variable can be used or referred as string, number or object. The __toString() method is called when the code attempts to treat an object like a string. This function does not accept any arguments and should return a string. The purpose of the __toString() is to return a string value of an object. The main use of __toString() function is to print the methods and attributes of the class. This information can be useful in debugging. A simple example will explain the implementation and use of __toString().

class TestClass{

private $name = "Refulz PHP";

private $tagline = "Web Developer's Blog";

}

$obj = new TestClass();

echo $obj;

The above code will give you a fatal E_RECOVERABLE_ERROR error. But, if you add a __toString() method in the class, then it wil handle the string conversion. Additionally, the method can be programmed to output or return any useful information for debugging.

class TestClass{

private $name = "Refulz PHP";

private $tagline = "Web Developer's Blog";

public function __toString(){

return $this->name . " - " . $this->tagline ;

}

}

$obj = new TestClass();

echo $obj;

Output: Refulz PHP - Web Developer's Blog 

The class object $obj gets converted into string type. If defined in the class, the __toString() is automatically called whenever such a conversion happens.

_toString – Before PHP 5.2 and PHP 5.2 Onwards

As per the PHP documentation, “Before PHP 5.2.0 the __toString() method was only called when it was directly combined with echo() or print(). Since PHP 5.2.0, it is called in any string context (e.g. in printf() with %s modifier) but not in other types contexts (e.g. with %d modifier).

So, since PHP 5.2 onwards, there are few changes in the way the function responds. What are those changes?

Extending the above example, we will see which syntax works with prior to PHP 5.2 and PHP 5.2 onwards.

SYNTAXES FOR PHP < 5.2.0

$obj = new TestClass();

// Following 2 syntaxes work and call __toString() method

echo $obj;

echo 'Blog: ' . $obj->__toString();

// Following 3 syntaxes fail to call __toString() method

printf("%s", $obj);

echo 'Blog: ' . $obj;

echo (string)$obj;

//--------------------------------------------------------------------

SYNTAXES FOR PHP >= 5.2.0

$obj = new TestClass();

// All 5 syntaxes work and call __toString() method

echo $obj;

echo 'Blog: ' . $obj->__toString();

printf("%s", $obj);

echo 'Blog: ' . $obj;

echo (string)$obj;

The __toString() method can also be used to return error messages when someone tries to print class details.

class TestClass{

public function __toString(){

return "You are not allowed to access the Object of this class";

}

$obj = new TestClass();

echo $obj;

Output: You are not allowed to access the Object of this class 

The __toString() method can be put to many innovative uses. It can also be used to write the object state in the log file. In such case, it is advised to not include sensitive information like passwords and information like credit card details in the __toString() method.

Series NavigationThe __get() Method – Reading Undeclared Properties >>The __set() Method – Writing Inaccessible Properties >>