Re: improvement to instanceof docs

Hi Greg Looks good to me... Marcus: can you check the "OO grammar" ("instantiated object of a class"...) :) -Hannes On 2/14/07, Gregory Beaver <greg@chiaraquartet.net> wrote:

Hi all, Etienne was asking about wording of the instanceof docs, and I got inspired by their, um, greatness to improve them. Attached is a patch for review. An earlier version I sent to Etienne had a small but significant typo in the instanceof parentclass example, which is fixed. Thanks, Greg ? XML_XUL-0.8.3.tgz ? channel.xml ? instanceof.patch.txt ? phar.patch ? en/functions.xml ? en/reference/monetra/functions.xml ? en/reference/mysqli/mysqli/functions.xml ? en/reference/statistics/functions.xml Index: en/language/operators.xml =================================================================== RCS file: /repository/phpdoc/en/language/operators.xml,v retrieving revision 1.109 diff -u -r1.109 operators.xml

--- en/language/operators.xml   30 Nov 2006 14:54:54 -0000      1.109

+++ en/language/operators.xml 14 Feb 2007 04:52:36 -0000 @@ -1157,41 +1157,157 @@ <sect1 id="language.operators.type">

    <title>Type Operators</title>
    <para>
-    PHP has a single type operator: <literal>instanceof</literal> is used to
-    determine whether a given object, his parents or their implemented <link
-    linkend="language.oop5.interfaces">interfaces</link> are of a specified
-    <link linkend="language.oop5.basic.class">object class</link>.

- </para> - <simpara>

-    The <literal>instanceof</literal> operator was introduced in PHP 5.
-    Before this time <function>is_a</function> was used but
-    <function>is_a</function> has since been deprecated in favor of
-    <literal>instanceof</literal>.

- </simpara> - <informalexample>

-    <programlisting role="php">
+    <literal>instanceof</literal> is used to determine whether a PHP variable
+    is an instantiated object of a certain
+    <link linkend="language.oop5.basic.class">class</link>:
+    <example>
+     <title>Using instanceof with classes</title>
+     <programlisting role="php">
+     <![CDATA[

+<?php +class MyClass +{ +} +class NotMyClass +{ +} +$a = new MyClass; + +var_dump($a instanceof MyClass); +var_dump($a instanceof NotMyClass); +?>

+     ]]>
+    </programlisting>
+    &example.outputs;
+    <screen>

<![CDATA[ +bool(true) +bool(false) +]]>

+     </screen>
+    </example>
+    <literal>instanceof</literal> can also be used to determine whether a variable
+    is an instantiated object of a class that inherits from a parent class:
+    <example>
+     <title>Using instanceof with inherited classes</title>
+     <programlisting role="php">
+     <![CDATA[

<?php -class A { } -class B { } +class ParentClass +{ +} +class MyClass extends ParentClass +{ +} +$a = new MyClass; -$thing = new A; +var_dump($a instanceof MyClass); +var_dump($a instanceof ParentClass); +?>

+     ]]>
+    </programlisting>
+    &example.outputs;
+    <screen>

+<![CDATA[ +bool(true) +bool(true) +]]>

+     </screen>
+    </example>
+    Lastly, <literal>instanceof</literal> can also be used to determine whether
+    a variable is an instantiated object of a class that implements an
+    <link linkend="language.oop5.interfaces">interface</link>:
+    <example>
+     <title>Using instanceof for class</title>
+     <programlisting role="php">
+     <![CDATA[

+<?php +interface MyInterface +{ +} +class MyClass implements MyInterface +{ +} +$a = new MyClass; -if ($thing instanceof A) {

-    echo 'A';

+var_dump($a instanceof MyClass); +var_dump($a instanceof MyInterface); +?>

+     ]]>
+    </programlisting>
+    &example.outputs;
+    <screen>

+<![CDATA[ +bool(true) +bool(true) +]]>

+     </screen>
+    </example>

+ </para> + <para>

+    Although <literal>instanceof</literal> is usually used with a literal classname,
+    it can also be used with another object or a string variable:
+    <example>
+     <title>Using instanceof with other variables</title>
+     <programlisting role="php">
+     <![CDATA[

+<?php +interface MyInterface +{ } -if ($thing instanceof B) {

-    echo 'B';

+class MyClass implements MyInterface +{ } +$a = new MyClass; +$b = new MyClass; +$c = 'MyClass'; +$d = 'NotMyClass'; +var_dump($a instanceof $b); // $b is an object of class MyClass +var_dump($a instanceof $c); // $c is a string 'MyClass' +var_dump($a instanceof $d); // $d is a string 'NotMyClass' ?>

+     ]]>
+    </programlisting>
+    &example.outputs;
+    <screen>

+<![CDATA[ +bool(true) +bool(true) +bool(false) ]]>

+     </screen>
+    </example>

+ </para> + <para>

+    There are a few pitfalls to be aware of.  Before PHP version 5.1.0,
+    <literal>instanceof</literal> would call <link linkend="language.oop5.autoload">__autoload()</link>
+    if the class name did not exist.  In addition, if the class was not loaded,
+    a fatal error would occur.  This can be worked around by using a <literal>dynamic
+    class reference</literal>, or a string variable containing the class name:
+    <example>
+     <title>Avoiding classname lookups and fatal errors with instanceof in PHP 5.0</title>
+     <programlisting role="php">
+     <![CDATA[

+<?php +$d = 'NotMyClass'; +var_dump($a instanceof $d); // no fatal error here +?>

+     ]]>
     </programlisting>
-    <simpara>
-     As <varname>$thing</varname> is an <type>object</type> of type A, but
-     not B, only the block dependent on the A type will be executed:
-    </simpara>
-    <screen>A</screen>

- </informalexample>

+    &example.outputs;
+    <screen>

+<![CDATA[ +bool(false) +]]>

+     </screen>
+    </example>

+ </para> + <simpara>

+    The <literal>instanceof</literal> operator was introduced in PHP 5.
+    Before this time <function>is_a</function> was used but
+    <function>is_a</function> has since been deprecated in favor of
+    <literal>instanceof</literal>.

+ </simpara>

    <para>
     See also <function>get_class</function> and
     <function>is_a</function>.