From dcf481b64f18d483fcdd248cb13093002a3daaec Mon Sep 17 00:00:00 2001
From: Thomas Punt <tpunt@php.net>
Date: Fri, 8 Jan 2016 17:38:43 +0000
Subject: [PATCH] Modernise autoloading page

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@338442 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/oop5/autoload.xml | 53 ++++++++++++++++++++------------------
 1 file changed, 28 insertions(+), 25 deletions(-)

diff --git a/language/oop5/autoload.xml b/language/oop5/autoload.xml
index 9ecac63163..506a728ca3 100644
--- a/language/oop5/autoload.xml
+++ b/language/oop5/autoload.xml
@@ -9,29 +9,32 @@
    at the beginning of each script (one for each class).
   </para>
   <para>
-   In PHP 5, this is no longer necessary. You may define an
-   <function>__autoload</function> function which is automatically
-   called in case you are trying to use a class/interface which hasn't been
-   defined yet. By calling this function the scripting engine is given
-   a last chance to load the class before PHP fails with an error.
+   In PHP 5, this is no longer necessary. The
+   <function>spl_autoload_register</function> function registers any number of
+   autloaders, enabling for classes and interfaces to be automatically loaded
+   if they are currently not defined. By registering autoloaders, PHP is given
+   a last chance to load the class or interface before it fails with an error.
   </para>
   <tip>
    <para>
-    <function>spl_autoload_register</function> provides a more flexible
-    alternative for autoloading classes. For this reason, using
-    <function>__autoload</function> is discouraged and may be deprecated or
-    removed in the future.
+    Whilst the <function>__autoload</function> function can also be used for
+    autoloading classes and interfaces, its preferred to use the
+    <function>spl_autoload_register</function> function. This is because it is
+    a more flexible alternative (enabling for any number of autoloaders to be
+    specified in the application, such as in third party libraries). For this
+    reason, using <function>__autoload</function> is discouraged and it may be
+    deprecated in the future.
    </para>
   </tip>
   <note>
    <para>
-    Prior to 5.3.0, exceptions thrown in the __autoload function could not be
-    caught in the <link linkend="language.exceptions">catch</link> block and
-    would result in a fatal error. From 5.3.0+ exceptions thrown in the
-    __autoload function can be caught in the <link linkend="language.exceptions">
-    catch</link> block, with 1 provision. If throwing a custom exception, then
-    the custom exception class must be available. The __autoload function may
-    be used recursively to autoload the custom exception class.
+    Prior to PHP 5.3, exceptions thrown in the <function>__autoload</function>
+    function could not be caught in the
+    <link linkend="language.exceptions">catch</link> block and would result in
+    a fatal error. From PHP 5.3 and upwards, this is possible provided that if
+    a custom exception is thrown, then the custom exception class is available.
+    The <function>__autoload</function> function may be used recursively to
+    autoload the custom exception class.
    </para>
   </note>
   <note>
@@ -59,9 +62,9 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-function __autoload($class_name) {
+spl_autoload_register(function ($class_name) {
     include $class_name . '.php';
-}
+});
 
 $obj  = new MyClass1();
 $obj2 = new MyClass2(); 
@@ -78,9 +81,9 @@ $obj2 = new MyClass2();
 <![CDATA[
 <?php
 
-function __autoload($name) {
+spl_autoload_register(function ($name) {
     var_dump($name);
-}
+});
 
 class Foo implements ITest {
 }
@@ -102,10 +105,10 @@ Fatal error: Interface 'ITest' not found in ...
     <programlisting role="php">
 <![CDATA[
 <?php
-function __autoload($name) {
+spl_autoload_register(function ($name) {
     echo "Want to load $name.\n";
     throw new Exception("Unable to load $name.");
-}
+});
 
 try {
     $obj = new NonLoadableClass();
@@ -131,10 +134,10 @@ Unable to load NonLoadableClass.
     <programlisting role="php">
 <![CDATA[
 <?php
-function __autoload($name) {
+spl_autoload_register(function ($name) {
     echo "Want to load $name.\n";
     throw new MissingException("Unable to load $name.");
-}
+});
 
 try {
     $obj = new NonLoadableClass();
@@ -163,7 +166,7 @@ Fatal error: Class 'MissingException' not found in testMissingException.php on l
      <member><function>unserialize</function></member>
      <member><link linkend="unserialize-callback-func">unserialize_callback_func</link></member>
      <member><function>spl_autoload</function></member>
-     <member><function>spl_autoload_register</function></member>
+     <member><function>__autoload</function></member>
     </simplelist>
    </para>
   </simplesect>