feature #3686 Documentation of the new PSR-4 class loader. (derrabus)

This PR was merged into the master branch.

Discussion
----------

Documentation of the new PSR-4 class loader.

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#10100)
| Applies to    | 2.5+
| Fixed tickets | #3655

Hello docs team,

this is a first draft of a documentation for the PSR-4 class loaded I've contributed. As this is my first contribution to the documentation, any assistance would be appreciated. :-)

Commits
-------

cb2be4a Moved versionadded block to the top.
16fead4 Adjustments from comments by @bicpi
a05da41 Minor corrections.
6f2a1a3 Adjustments from comments be @wouterj
17166bd First shot of a documentation of the new PSR-4 class loader.

components/class_loader/index.rst

@@ -6,6 +6,7 @@ ClassLoader
 
     introduction
     class_loader
+    psr4_class_loader
     map_class_loader
     cache_class_loader
     debug_class_loader

components/class_loader/psr4_class_loader.rst

@@ -0,0 +1,67 @@
+.. index::
+   single: ClassLoader; PSR-4 Class Loader
+
+The PSR-4 Class Loader
+======================
+
+.. versionadded:: 2.5
+    The :class:`Symfony\\Component\\ClassLoader\\Psr4ClassLoader` was
+    introduced in Symfony 2.5.
+
+Libraries that follow the `PSR-4`_ standard can be loaded with the ``Psr4ClassLoader``.
+
+.. note::
+
+    If you manage your dependencies via Composer, you get a PSR-4 compatible
+    autoloader out of the box. Use this loader in environments where Composer
+    is not available.
+
+.. tip::
+
+    All Symfony components follow PSR-4.
+
+Usage
+-----
+
+The following example demonstrates how you can use the
+:class:`Symfony\\Component\\ClassLoader\\Psr4ClassLoader` autoloader to use
+Symfony's Yaml component. Imagine, you downloaded both the ClassLoader and
+Yaml component as ZIP packages and unpacked them to a ``libs`` directory.
+The directory structure will look like this:
+
+.. code-block:: text
+
+    libs/
+        ClassLoader/
+            Psr4ClassLoader.php
+            ...
+        Yaml/
+            Yaml.php
+            ...
+    config.yml
+    demo.php
+
+In ``demo.php`` you are going to parse the ``config.yml`` file. To do that, you
+first need to configure the ``Psr4ClassLoader``:
+
+.. code-block:: php
+
+    use Symfony\Component\ClassLoader\Psr4ClassLoader;
+    use Symfony\Component\Yaml\Yaml;
+
+    require __DIR__.'/lib/ClassLoader/Psr4ClassLoader.php';
+
+    $loader = new Psr4ClassLoader();
+    $loader->addPrefix('Symfony\\Component\\Yaml\\', __DIR__.'/lib/Yaml');
+    $loader->register();
+
+    $data = Yaml::parse(__DIR__.'/config.yml');
+
+First of all, the class loader is loaded manually using a ``require``
+statement, since there is no autoload mechanism yet. With the
+:method:`Symfony\Component\ClassLoader\Psr4ClassLoader::addPrefix` call, you
+tell the class loader where to look for classes with the
+``Symfony\Component\Yaml\`` namespace prefix. After registering the autoloader,
+the Yaml component is ready to be used.
+
+.. _PSR-4: http://www.php-fig.org/psr/psr-4/

components/map.rst.inc

@@ -4,6 +4,7 @@
 
   * :doc:`/components/class_loader/introduction`
   * :doc:`/components/class_loader/class_loader`
+  * :doc:`/components/class_loader/psr4_class_loader`
   * :doc:`/components/class_loader/map_class_loader`
   * :doc:`/components/class_loader/cache_class_loader`
   * :doc:`/components/class_loader/debug_class_loader`