From afdb316652ff839ed9647d449c51050b1a0ab819 Mon Sep 17 00:00:00 2001
From: Simion Onea <simionea@php.net>
Date: Thu, 27 Sep 2007 13:16:10 +0000
Subject: [PATCH] Added necessary DocBook elements in appropriate places.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@242985 c90b9560-bf6c-de11-be94-00142212c4b1
---
appendices/migration51.xml | 149 +++++++++++++++++++++----------------
1 file changed, 83 insertions(+), 66 deletions(-)
diff --git a/appendices/migration51.xml b/appendices/migration51.xml
index 34766164c7..e58df738b5 100644
--- a/appendices/migration51.xml
+++ b/appendices/migration51.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<appendix xml:id="migration51" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Migrating from PHP 5.0.x to PHP 5.1.x</title>
@@ -118,7 +118,8 @@ $bar = &return_value();
fixed to 'know' when the reference operation is being used on a value
that should not be referenced. The actual value is now used in such
cases, and a warning is emitted. The warning takes the form of an
- E_NOTICE in PHP 4.4.0 and up, and E_STRICT in PHP 5.0.4 and up.
+ <constant>E_NOTICE</constant> in PHP 4.4.0 and up, and
+ <constant>E_STRICT</constant> in PHP 5.0.4 and up.
</para>
<para>
Code that could potentially produce memory corruption can no longer do
@@ -179,17 +180,18 @@ array(3) {
</screen>
</informalexample>
<para>
- This is because, following the changes, func() assigns by value. The value
- of $y is re-assigned, and reference-binding is preserved from $z. Prior to
- the fix, the value was assigned by reference, leading $y to be re-bound on
- each assignment. The attempt to bind to a temporary value by reference was
- the cause of the memory corruption.
+ This is because, following the changes, <literal>func()</literal>
+ assigns by value. The value of <varname>$y</varname> is re-assigned,
+ and reference-binding is preserved from <varname>$z</varname>. Prior to
+ the fix, the value was assigned by reference, leading <varname>$y</varname>
+ to be re-bound on each assignment. The attempt to bind to a temporary
+ value by reference was the cause of the memory corruption.
</para>
<para>
Such code can be made to work identically in both the pre-fix and the
- post-fix PHP versions. The signature of func() can be altered to return by
- reference, or the reference assignment can be removed from the result of
- func().
+ post-fix PHP versions. The signature of <literal>func()</literal> can
+ be altered to return by reference, or the reference assignment can be
+ removed from the result of <literal>func()</literal>.
</para>
<informalexample>
<programlisting role="php">
@@ -208,12 +210,12 @@ echo $x;
</programlisting>
</informalexample>
<para>
- In PHP 4.3 $x would be 'original value', whereas after the changes it
- would be 'function return' - remember that where the function does not
- return by reference, the reference assignment is converted to a regular
- assignment. Again, this can be brought to a common base, either by forcing
- func() to return by reference or by eliminating the by-reference
- assignment.
+ In PHP 4.3 <varname>$x</varname> would be 'original value', whereas after
+ the changes it would be 'function return' - remember that where the
+ function does not return by reference, the reference assignment is
+ converted to a regular assignment. Again, this can be brought to a common
+ base, either by forcing <literal>func()</literal> to return by reference
+ or by eliminating the by-reference assignment.
</para>
</section>
@@ -242,11 +244,12 @@ var_dump($bar);
</programlisting>
</informalexample>
<para>
- In PHP 5.0.3, $bar evaluated to NULL instead of returning an object. That
- happened because getThis() returns by value, but the value here is
+ In PHP 5.0.3, <varname>$bar</varname> evaluated to <literal>NULL</literal>
+ instead of returning an object. That happened because
+ <literal>getThis()</literal> returns by value, but the value here is
assigned by reference. Although it now works in the expected way, this is
- actually invalid code which will throw an E_NOTICE under PHP 4.4 or an
- E_STRICT under PHP 5.0.4 and up.
+ actually invalid code which will throw an <constant>E_NOTICE</constant>
+ under PHP 4.4 or an <constant>E_STRICT</constant> under PHP 5.0.4 and up.
</para>
</section>
@@ -270,10 +273,10 @@ for ($i = 0; $i < 3; $i++) {
]]>
</programlisting>
<para>
- In PHP 4.3 the third call to var_dump produces NULL, due to the memory
- corruption caused by returning an uninitialized value by reference. This
- is valid code in PHP 5.0.4 and up, but threw errors in earlier releases
- of PHP.
+ In PHP 4.3 the third call to <function>var_dump</function> produces
+ <constant>NULL</constant>, due to the memory corruption caused by
+ returning an uninitialized value by reference. This is valid code
+ in PHP 5.0.4 and up, but threw errors in earlier releases of PHP.
</para>
</informalexample>
<informalexample>
@@ -299,10 +302,11 @@ echo '-'.$arr['alfa']."-\n";
There are a couple of instances of bugs reported under PHP 5.0 prior to
the reference fixes which now 'work'. However, in both cases errors are
thrown by PHP 5.1.x, because the code was invalid in the first place.
- Returning values by reference using self:: now works in the general case
- but throws an E_STRICT warning, and although your mileage may vary when
- assigning by reference to an overloaded object, you will still see an
- E_ERROR when you try it, even where the assignment itself appears to work.
+ Returning values by reference using <literal>self::</literal> now works
+ in the general case but throws an <constant>E_STRICT</constant> warning,
+ and although your mileage may vary when assigning by reference to an
+ overloaded object, you will still see an <constant>E_ERROR</constant>
+ when you try it, even where the assignment itself appears to work.
</para>
</section>
@@ -310,8 +314,9 @@ echo '-'.$arr['alfa']."-\n";
<title>Warnings that came and went</title>
<para>
Nested calls to functions returning by reference are valid code under both
- PHP 4.3.x and PHP 5.1.x, but threw an unwarranted E_NOTICE or E_STRICT under
- the intervening PHP releases.
+ PHP 4.3.x and PHP 5.1.x, but threw an unwarranted
+ <constant>E_NOTICE</constant> or <constant>E_STRICT</constant> under the
+ intervening PHP releases.
</para>
<informalexample>
<programlisting role="php">
@@ -363,8 +368,9 @@ $o->run();
</programlisting>
</informalexample>
<para>
- This should always have thrown a fatal E_ERROR, because [] cannot be used
- for reading in PHP. It is invalid code in PHP 4.4.2 and PHP 5.0.5 upward.
+ This should always have thrown a fatal <constant>E_ERROR</constant>,
+ because [] cannot be used for reading in PHP. It is invalid code in
+ PHP 4.4.2 and PHP 5.0.5 upward.
</para>
</section>
@@ -378,8 +384,8 @@ $o->run();
integer. These checks have now been relaxed to support non-well formed
numeric strings such as " 123" and "123 ", and will no longer fail as they
did under PHP 5.0.x. However, to promote code safety and input validation,
- PHP functions will now emit an E_NOTICE when such strings are passed as
- integers.
+ PHP functions will now emit an <constant>E_NOTICE</constant> when such
+ strings are passed as integers.
</para>
</section>
@@ -388,8 +394,9 @@ $o->run();
<itemizedlist>
<listitem>
<para>
- <link linkend="migration51.oop-functions">instanceof, is_a(),
- is_subclass_of() and catch</link>
+ <link linkend="migration51.oop-functions"><literal>instanceof</literal>,
+ <literal>is_a()</literal>, <literal>is_subclass_of()</literal> and
+ <literal>catch</literal></link>
</para>
</listitem>
<listitem>
@@ -417,20 +424,24 @@ $o->run();
</itemizedlist>
<section xml:id="migration51.oop-functions">
- <title>instanceof, is_a(), is_subclass_of() and catch</title>
+ <title><literal>instanceof</literal>, <literal>is_a()</literal>,
+ <literal>is_subclass_of()</literal> and <literal>catch</literal></title>
<para>
- In PHP 5.0, is_a() was deprecated and replaced by the "instanceof"
- operator. There were some issues with the initial implementation of
- "instanceof", which relied on __autoload() to search for missing classes.
- If the class was not present, "instanceof" would throw a fatal E_ERROR due
- to the failure of __autoload() to discover that class. The same behaviour
- occurred in the "catch" operator and the is_subclass_of() function, for
- the same reason.
+ In PHP 5.0, <literal>is_a()</literal> was deprecated and replaced by the
+ <literal>instanceof</literal> operator. There were some issues with the
+ initial implementation of <literal>instanceof</literal>, which relied on
+ <literal>__autoload()</literal> to search for missing classes.
+ If the class was not present, <literal>instanceof</literal> would throw
+ a fatal <constant>E_ERROR</constant> due to the failure of
+ <literal>__autoload()</literal> to discover that class. The same behaviour
+ occurred in the <literal>catch</literal> operator and the
+ <literal>is_subclass_of()</literal> function, for the same reason.
</para>
<para>
- None of these functions or operators call __autoload() in PHP 5.1.x, and the
- class_exists() workarounds used in code written for PHP 5.0.x, while not
- problematic in any way, are no longer necessary.
+ None of these functions or operators call <literal>__autoload()</literal>
+ in PHP 5.1.x, and the <literal>class_exists()</literal> workarounds used
+ in code written for PHP 5.0.x, while not problematic in any way, are no
+ longer necessary.
</para>
</section>
@@ -438,8 +449,9 @@ $o->run();
<title>Abstract private methods</title>
<para>
Abstract private methods were supported between PHP 5.0.0 and PHP 5.0.4,
- but were then disallowed on the grounds that the behaviours of 'private'
- and 'abstract' are mutually exclusive.
+ but were then disallowed on the grounds that the behaviours of
+ <literal>private</literal> and <literal>abstract</literal> are mutually
+ exclusive.
</para>
</section>
@@ -448,13 +460,15 @@ $o->run();
<para>
Under PHP 5.0, function declarations in interfaces were treated in exactly
the same way as function declarations in classes. This has not been the
- case since October 2004, at which point only the 'public' access modifier
- was allowed in interface function declarations. Since April 2005 - which
- pre-dates the PHP 5.0b1 release - the 'static' modifier has also been
- allowed. However, the 'protected' and 'private' modifiers will now throw
- an E_ERROR, as will 'abstract'. Note that this change should not affect
- your existing code, as none of these modifiers makes sense in the context
- of interfaces anyway.
+ case since October 2004, at which point only the <literal>public</literal>
+ access modifier was allowed in interface function declarations. Since
+ April 2005 - which pre-dates the PHP 5.0b1 release - the
+ <literal>static</literal> modifier has also been allowed. However, the
+ <literal>protected</literal> and <literal>private</literal> modifiers will
+ now throw an <constant>E_ERROR</constant>, as will
+ <literal>abstract</literal>. Note that this change should not affect your
+ existing code, as none of these modifiers makes sense in the context of
+ interfaces anyway.
</para>
</section>
@@ -467,7 +481,8 @@ $o->run();
</para>
<informalexample>
<para>
- This code will cause an E_STRICT error to be emitted under PHP 5.1.x.
+ This code will cause an <constant>E_STRICT</constant> error to be emitted
+ under PHP 5.1.x.
</para>
<programlisting role="php">
<![CDATA[
@@ -498,7 +513,7 @@ class Derived extends Base {
<informalexample>
<para>
Under PHP 5.1.x, redefinition of a class constant will throw a fatal
- E_ERROR.
+ <constant>E_ERROR</constant>.
</para>
<programlisting role="php">
<![CDATA[
@@ -637,8 +652,8 @@ class test {
<link linkend="ref.pdo">PDO</link>,
<link linkend="ref.xmlreader">XMLReader</link> and
<link linkend="ref.datetime">date</link>, have their constants in
- the format <literal>PDO::CLASS_CONSTANT</literal> rather than in the C
- format <literal>PDO_CLASS_CONSTANT</literal> in order to minimise
+ the format <constant>PDO::CLASS_CONSTANT</constant> rather than in the C
+ format <constant>PDO_CLASS_CONSTANT</constant> in order to minimise
pollution of the global namespace in PHP.
</para>
</section>
@@ -676,8 +691,9 @@ class test {
</itemizedlist>
<informalexample>
<para>
- To ensure accuracy (and avoid an E_STRICT warning), you will need to define
- your timezone in your php.ini using the following format:
+ To ensure accuracy (and avoid an <constant>E_STRICT</constant> warning),
+ you will need to define your timezone in your <filename>php.ini</filename>
+ using the following format:
</para>
<para>
date.timezone = Europe/London
@@ -688,7 +704,8 @@ class test {
<link linkend="timezones">timezones appendix</link>.
</para>
<para>
- Also note that <function>strtotime</function> now returns &false; on failure, instead of -1.
+ Also note that <function>strtotime</function> now returns &false; on
+ failure, instead of -1.
</para>
</section>
@@ -801,8 +818,9 @@ class test {
<title>Checking for <literal>E_STRICT</literal></title>
<informalexample>
<para>
- If you only have a single script to check, you can pick up E_STRICT errors
- using PHP's commandline lint facility:
+ If you only have a single script to check, you can pick up
+ <constant>E_STRICT</constant> errors using PHP's commandline lint
+ facility:
</para>
<programlisting role="shell">
php -d error_reporting=4095 -l script_to_check.php
@@ -874,4 +892,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-