mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Added necessary DocBook elements in appropriate places.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@242985 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Simion Onea
parent
6b808d6276
commit
afdb316652
1 changed files with 83 additions and 66 deletions
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue