From 0cdc5ae1dbf66902d990c02363bd579b8e971fa3 Mon Sep 17 00:00:00 2001
From: Adam Harvey <aharvey@php.net>
Date: Mon, 12 Nov 2012 03:43:29 +0000
Subject: [PATCH] Update the 5.3 migration guide with the various suggestions
 Ferenc made a while back. Additionally, link the configuration directives
 consistently.

Fixes doc bug #52524 (the 5.3 migration documentation lacks some details).


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328316 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/migration53.xml | 132 ++++++++++++++++++++++---------------
 1 file changed, 80 insertions(+), 52 deletions(-)

diff --git a/appendices/migration53.xml b/appendices/migration53.xml
index a5a77ba977..eb84cffdbf 100644
--- a/appendices/migration53.xml
+++ b/appendices/migration53.xml
@@ -259,24 +259,62 @@
    </listitem>
    <listitem>
     <simpara>
-     Dynamic access to static methods is now possible.
+     Dynamic access to static methods is now possible:
+    </simpara>
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+class C {
+   public static $foo = 123;
+}
+
+$a = "C";
+echo $a::$foo;
+?>
+]]>
+     </programlisting>
+     &example.outputs;
+     <screen>
+<![CDATA[
+123
+]]>
+     </screen>
+    </informalexample>
+   </listitem>
+   <listitem>
+    <simpara>
+     <link linkend="language.exceptions">Exceptions</link> can now be nested:
+    </simpara>
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+class MyCustomException extends Exception {}
+
+try {
+    throw new MyCustomException("Exceptional", 112);
+} catch (Exception $e) {
+    /* Note the use of the third parameter to pass $e
+     * into the RuntimeException. */
+    throw new RuntimeException("Rethrowing", 911, $e);
+}
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </listitem>
+   <listitem>
+    <simpara>
+     A <link linkend="features.gc">garbage collector</link> for circular
+     references has been added, and is enabled by default.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
-     <link linkend="language.exceptions">Exceptions</link> can now be nested.
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     A garbage collector for circular references has been added, and is enabled 
-     by default.
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     The <function>mail</function> function now supports logging of sent email.
-     (Note: This only applies to email sent through this function.)
+     The <function>mail</function> function now supports logging of sent email
+     via the <link linkend="ini.mail.log">mail.log</link> configuration
+     directive. (Note: This only applies to email sent through this function.)
     </simpara>
    </listitem>
   </itemizedlist>
@@ -2217,23 +2255,25 @@
    </listitem>
    <listitem>
     <simpara>
-     <literal>zend_extension_debug</literal> and
-     <literal>zend_extension_ts</literal> have been removed. Use the
-     <literal>zend_extension</literal> directive to load all Zend Extensions.
+     <link linkend="ini.zend-extension-debug">zend_extension_debug</link>,
+     <link linkend="ini.zend-extension-debug-ts">zend_extension_debug_ts</link>
+     and <link linkend="ini.zend-extension-ts">zend_extension_ts</link> have
+     been removed. Use the
+     <link linkend="ini.zend-extension">zend_extension</link> directive to
+     load all Zend Extensions.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
-     <literal>zend.ze1_compatibility_mode</literal> has been removed. If this 
-     INI directive is set to On, an <constant>E_ERROR</constant> error is 
-     emitted at startup.
+     <link linkend="ini.zend.ze1-compatibility-mode">zend.ze1_compatibility_mode</link>
+     has been removed. If this INI directive is set to On, an
+     <constant>E_ERROR</constant> error is emitted at startup.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      It is now possible to use the full path to load modules using the 
-     "<link linkend="ini.extension"><literal>extension</literal></link>"
-     directive.
+     <link linkend="ini.extension">extension</link> directive.
     </simpara>
    </listitem>
    <listitem>
@@ -2244,8 +2284,8 @@
    </listitem>
    <listitem>
     <simpara>
-     Runtime tightening of <literal>open_basedir</literal> restrictions is now
-     possible.
+     <link linkend="ini.open-basedir">open_basedir</link> restrictions may now
+     be tighted at runtime, and the directive is now PHP_INI_ALL.
     </simpara>
    </listitem>
    <listitem>
@@ -2261,27 +2301,9 @@
    </listitem>
    <listitem>
     <simpara>
-     A new directive, mail.add_x_header, has been added.
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     user_ini.filename is new
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     user_ini.cache_ttl is also new
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     exit_on_timeout is new too
-    </simpara>
-   </listitem>
-   <listitem>
-    <simpara>
-     open_basedir is now PHP_INI_ALL
+     Two new mail directives:
+     <link linkend="ini.mail.add-x-header">mail.add_x_header</link> and
+     <link linkend="ini.mail.log">mail.log</link>, have been added.
     </simpara>
    </listitem>
   </itemizedlist>
@@ -2292,8 +2314,14 @@
    <listitem>
     <simpara>
      <literal>user_ini.filename</literal> and
-     <literal>user_ini.cache_ttl</literal> for the new .htaccess-style user INI
-     file mechanism.
+     <literal>user_ini.cache_ttl</literal> have been added to control the use
+     of <link linkend="configuration.file.per-user">user INI files</link>.
+    </simpara>
+   </listitem>
+   <listitem>
+    <simpara>
+     <link linkend="ini.exit-on-timeout">exit_on_timeout</link> has been added
+     to force Apache 1.x children to exit if a PHP execution timeout occurs.
     </simpara>
    </listitem>
    <listitem>
@@ -2305,7 +2333,7 @@
    </listitem>
    <listitem>
     <simpara>
-     Added <literal>request_order</literal>.
+     Added <link linkend="ini.request-order">request_order</link>.
      Allows controlling which external variables will be available in
      <varname>$_REQUEST</varname>.
     </simpara>
@@ -2317,14 +2345,14 @@
   <itemizedlist>
    <listitem>
     <simpara>
-     <literal>session.use_only_cookies</literal> is now set to
-     <literal>"1"</literal> (enabled) by default.
+     <link linkend="ini.session.use-only-cookies">session.use_only_cookies</link>
+     is now set to <literal>"1"</literal> (enabled) by default.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
-     <literal>oci8.default_prefetch</literal> has changed from
-     <literal>"10"</literal> to <literal>"100"</literal>.
+     <link linkend="ini.oci8.default-prefetch">oci8.default_prefetch</link>
+     has changed from <literal>"10"</literal> to <literal>"100"</literal>.
     </simpara>
    </listitem>
   </itemizedlist>