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>.
