From 7c461dd6d585104385aba5152f9c74a921310e57 Mon Sep 17 00:00:00 2001
From: Aidan Lister <aidan@php.net>
Date: Mon, 11 Oct 2004 06:27:51 +0000
Subject: [PATCH] Clarified when __toString is called (bug #30379)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@170420 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/oop5/magic.xml | 42 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/language/oop5/magic.xml b/language/oop5/magic.xml
index 30427394de..30f6588608 100644
--- a/language/oop5/magic.xml
+++ b/language/oop5/magic.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
  <sect1 id="language.oop5.magic">
   <title>Magic Methods</title>
   <para>
@@ -64,10 +64,12 @@
     The <literal>__toString</literal> method allows a class to decide
     how it will react when it is converted to a string.
    </para>
-   <programlisting role="php">
+   <example>
+    <title>Simple example</title>
+    <programlisting role="php">
 <![CDATA[
 <?php
-// Define a simple class
+// Declare a simple class
 class TestClass
 {
     public $foo;
@@ -85,13 +87,39 @@ $class = new TestClass('Hello');
 echo $class;
 ?>
 ]]>
-   </programlisting>
-   &example.outputs;
-   <screen>
+    </programlisting>
+    &example.outputs;
+    <screen>
 <![CDATA[
 Hello
 ]]>
-   </screen>
+    </screen>
+   </example>
+   <para>
+    It is worth noting that the <literal>__toString</literal> method
+    will only be called when it is directly combined with
+    <function>echo</function> or <function>print</function>.
+   </para>
+   <example>
+    <title>Cases where <literal>__toString</literal> is called</title>
+    <programlisting role="php">
+<![CDATA[
+<?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 (casted to string first)
+echo (string) $class;
+?>
+]]>
+    </programlisting>
+   </example>
   </sect2>
  </sect1>