PHP __toString

Summary: in this tutorial, you will learn how to use the PHP __toString() method to return the string representation of an object.

Introduction to the PHP __toString() method

The __toString() is one of a magic method in PHP. The following shows the syntax of the __toString() method:

public function __toString ( ) : stringCode language: PHP (php)

The __toString() method accepts no parameter and returns a string.

When you use an object as it were a string, PHP will automatically call the __toString() magic method. If the method doesn’t exist, PHP raises an error.

The following example defines the BankAccount class, creates a new instance of the BankAccount, and display it:

<?php

class BankAccount
{
	private $accountNumber;

	private $balance;

	public function __construct(
		$accountNumber,
		$balance
	) {
		$this->accountNumber = $accountNumber;
		$this->balance = $balance;
	}
}

$account = new BankAccount('123456789', 100);
echo $account;Code language: HTML, XML (xml)

PHP raises the following error:

PHP Fatal error:  Uncaught Error: Object of class BankAccount could not be converted to string...Code language: plaintext (plaintext)

To use the $account object as a string, you need to implement the __toString() method that returns the string representation of the BankAccount object. For example:

<?php

class BankAccount
{
	private $accountNumber;

	private $balance;

	public function __construct(
		$accountNumber,
		$balance
	) {
		$this->accountNumber = $accountNumber;
		$this->balance = $balance;
	}

	public function __toString()
	{
		return "Bank Account: $this->accountNumber. Balance: $$this->balance";
	}
}


$account = new BankAccount('123456789', 100);
echo $account;Code language: HTML, XML (xml)

In this example, the __toString() returns a string that contains the bank account number and its current balance. Here is the output:

Bank Account: 123456789. Balance: $100Code language: plaintext (plaintext)

Note that you can use the BankAccount object anywhere that accepts a string. For example, you can concatenate a string with the BankAccount object like this:

$account = new BankAccount('123456789', 100);

echo 'Bank information:' . $account;Code language: PHP (php)

Output:

Bank information:Bank Account: 123456789. Balance: $100Code language: plaintext (plaintext)

Returning value

In PHP 7.4, the __toString() method must return a string, otherwise PHP will throw an Error.

The following example defines the Quarter class that represents the quarter of the year. It implements the __toString() method that returns a number:

<?php

class Quarter
{
	private $number;

	public function __construct($number)
	{
		if ($number < 0 && $number > 4) {
			throw new InvalidArgumentException('Quarter must be between 1 and 4');
		}
		$this->number = $number;
	}

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

$quarter = new Quarter(1);
echo $quarter;
Code language: HTML, XML (xml)

PHP raises the following error:

Fatal error: Uncaught Error: Method Quarter::__toString() must return a string valueCode language: plaintext (plaintext)

PHP doesn’t coerce the number to a string in this case.

In PHP 8, you’ll get the same error. However, if you disable the strict typing, PHP will coerce the return value to a string value.

To disable the strict type, you the following statement:

declare(strict_types=0);Code language: PHP (php)

The following example works on PHP 8 with strict typing is disabled:

<?php

declare(strict_types=0);

class Quarter
{
	private $number;

	public function __construct($number)
	{
		if ($number < 0 && $number > 4) {
			throw new InvalidArgumentException('Quarter must be between 1 and 4');
		}
		$this->number = $number;
	}

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

$quarter = new Quarter(1);
echo $quarter;Code language: HTML, XML (xml)

Summary

• Implement the __toString() magic method to create the string representation of an object.
• The __toString() method must return a string value or PHP raises an error.