cellog Fri Feb 16 05:39:30 2007 UTC
Modified files:
/phpdoc/en/language operators.xml
Log:
improve instanceof docs
add explicit PHP examples for each kind of usage, plus note
about how to use it with dynamic class references
http://cvs.php.net/viewvc.cgi/phpdoc/en/language/operators.xml?r1=1.110&r2=1.111&diff_format=u
Index: phpdoc/en/language/operators.xml
diff -u phpdoc/en/language/operators.xml:1.110
phpdoc/en/language/operators.xml:1.111
--- phpdoc/en/language/operators.xml:1.110 Thu Feb 15 08:12:19 2007
+++ phpdoc/en/language/operators.xml Fri Feb 16 05:39:30 2007
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.110 $ -->
+<!-- $Revision: 1.111 $ -->
<chapter id="language.operators">
<title>Operators</title>
<simpara>
@@ -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>.
