documentation for the Class Loader component

components/class_loader/cache_class_loader.rst

@@ -0,0 +1,76 @@
+.. index::
+    single: APC; ApcClassLoader
+    single: Class Loader; ApcClassLoader
+    single: Class Loader; Cache
+    single: Class Loader; XcacheClassLoader
+    single: XCache; XcacheClassLoader
+
+Cache a Class Loader
+====================
+
+Introduction
+------------
+
+Finding the file for a particular class can be an expensive task. Luckily,
+the Class Loader Component comes with two classes to cache the mapping
+from a class to its containing file. Both the :class:`Symfonfy\\Component\\ClassLoader\\ApcClassLoader`
+and the :class:`Symfony\\Component\\ClassLoader\\XcacheClassLoader` wrap
+around an object which implements a ``findFile()`` method to find the file
+for a class.
+
+.. note::
+
+  Both the ``ApcClassLoader`` and the ``XcacheClassLoader`` can be used
+  to cache Composer's `autoloader`_.
+
+ApcClassLoader
+--------------
+
+.. versionadded:: 2.1
+    The ``ApcClassLoader`` class was added in Symfony 2.1.
+
+``ApcClassLoader`` wraps an existing class loader and caches calls to its
+``findFile()`` method using `APC`_::
+
+    require_once '/path/to/src/Symfony/Component/ClassLoader/ApcClassLoader.php';
+
+    // instance of a class that implements a findFile() method
+    $loader = ...;
+
+    // my_prefix is the APC namespace prefix to use
+    $cachedLoader = new ApcClassLoader('my_prefix', $loader);
+
+    // register the cached class loader
+    $cachedLoader->register();
+
+    // eventually deactivate the non-cached loader if it was registered
+    // previously
+    $loader->unregister();
+
+XcacheClassLoader
+-----------------
+
+.. versionadded:: 2.1
+    The ``XcacheClassLoader`` class was added in Symfony 2.1.
+
+``XcacheClassLoader`` uses `XCache`_ to cache a class loader. Registering
+it is straightforward::
+
+    require_once '/path/to/src/Symfony/Component/ClassLoader/XcacheClassLoader.php';
+
+    // instance of a class that implements a findFile() method
+    $loader = ...;
+
+    // my_prefix is the XCache namespace
+    $cachedLoader = new XcacheClassLoader('my_prefix', $loader);
+
+    // register the cached class loader
+    $cachedLoader->register();
+
+    // eventually deactivate the non-cached loader if it was registered
+    // previously
+    $loader->unregister();
+
+.. _APC:        http://php.net/manual/en/book.apc.php
+.. _autoloader: http://getcomposer.org/doc/01-basic-usage.md#autoloading
+.. _XCache:     http://xcache.lighttpd.net

components/class_loader/class_loader.rst

@@ -0,0 +1,87 @@
+.. index::
+   single: Class Loader; MapClassLoader
+
+The PSR-0 Class Loader
+======================
+
+Introduction
+------------
+
+.. versionadded:: 2.1
+    The ``ClassLoader`` class was added in Symfony 2.1.
+
+If your classes and third-party libraries follow the `PSR-0`_ standards or the
+`PEAR`_ naming conventions, you can use the :class:`Symfony\\Component\\ClassLoader\\ClassLoader`
+class to load all of your project's classes.
+
+.. note::
+
+    You can use both the ``ApcClassLoader`` and the ``XcacheClassLoader`` to
+    :doc:`cache</components/class_loader/cache_class_loader>` a ``ClassLoader``
+    instance or the ``DebugClassLoader`` to :doc:`debug</components/class_loader/debug_class_loader>`
+    it.
+
+Usage
+-----
+
+Registering the :class:`Symfony\\Component\\ClassLoader\\ClassLoader` autoloader
+is straightforward::
+
+    require_once '/path/to/src/Symfony/Component/ClassLoader/ClassLoader.php';
+
+    use Symfony\Component\ClassLoader\ClassLoader;
+
+    $loader = new ClassLoader();
+
+    // to enable searching the include path (eg. for PEAR packages)
+    $loader->useIncludePath(true);
+
+    // ... register namespaces and prefixes here - see below
+
+    $loader->register();
+
+.. note::
+
+    The autoloader is automatically registered in a Symfony2 application (see
+    ``app/autoload.php``).
+
+Use the :method:`Symfony\\Component\\ClassLoader\\ClassLoader::addPrefix` or
+:method:`Symfony\\Component\\ClassLoader\\ClassLoader::addPrefixes` methods to
+register your classes::
+
+    // register a single namespaces
+    $loader->addPrefix('Symfony', __DIR__.'/vendor/symfony/symfony/src');
+
+    // register several namespaces at once
+    $loader->addPrefixes(array(
+        'Symfony' => __DIR__.'/../vendor/symfony/symfony/src',
+        'Monolog' => __DIR__.'/../vendor/monolog/monolog/src',
+    ));
+
+    // register a prefix for a class following the PEAR naming conventions
+    $loader->addPrefix('Twig_', __DIR__.'/vendor/twig/twig/lib');
+
+    $loader->addPrefixes(array(
+        'Swift_' => __DIR__.'/vendor/swiftmailer/swiftmailer/lib/classes',
+        'Twig_'  => __DIR__.'/vendor/twig/twig/lib',
+    ));
+
+Classes from a sub-namespace or a sub-hierarchy of PEAR classes can be looked
+for in a location list to ease the vendoring of a sub-set of classes for large
+projects::
+
+    $loader->addPrefixes(array(
+        'Doctrine\\Common'           => __DIR__.'/vendor/doctrine/common/lib',
+        'Doctrine\\DBAL\\Migrations' => __DIR__.'/vendor/doctrine/migrations/lib',
+        'Doctrine\\DBAL'             => __DIR__.'/vendor/doctrine/dbal/lib',
+        'Doctrine'                   => __DIR__.'/vendor/doctrine/orm/lib',
+    ));
+
+In this example, if you try to use a class in the ``Doctrine\Common`` namespace
+or one of its children, the autoloader will first look for the class under the
+``doctrine-common`` directory, and it will then fallback to the default
+``Doctrine`` directory (the last one configured) if not found, before giving up.
+The order of the registrations is significant in this case.
+
+.. _PEAR:  http://pear.php.net/manual/en/standards.naming.php
+.. _PSR-0: http://symfony.com/PSR0

components/class_loader/debug_class_loader.rst

@@ -0,0 +1,21 @@
+.. index::
+    single: Class Loader; DebugClassLoader
+
+Debugging a Class Loader
+========================
+
+.. versionadded:: 2.1
+    The ``DebugClassLoader`` class was added in Symfony 2.1.
+
+When a class isn't found by the registered autoloaders you can use the
+:class:`Symfony\\Component\\ClassLoader\\DebugClassLoader`. All autoloaders
+which implement a ``findFile()`` method are replaced with a ``DebugClassLoader``
+wrapper. It throws an exception if a file is found but does not declare the
+class.
+
+Using the ``DebugClassLoader`` is as easy as calling its static :method:`DebugClassLoader::enable`
+method::
+
+    use Symfony\Component\ClassLoader\DebugClassLoader;
+
+    DebugClassLoader::enable();

components/class_loader/index.rst

@@ -0,0 +1,11 @@
+Class Loader
+============
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    class_loader
+    map_class_loader
+    cache_class_loader
+    debug_class_loader

components/class_loader/introduction.rst

@@ -0,0 +1,31 @@
+The Class Loader Component
+==========================
+
+    The Class Loader Component loads your project classes automatically.
+
+Whenever you use an undefined class, PHP uses the autoloading mechanism to
+delegate the loading of a file defining the class. Symfony2 provides two
+autoloaders, which are able to load your classes:
+
+* :doc:`A PSR-0 class loader<class_loader>`
+
+* :doc:`Load classes based on class-to-file mapping<map_class_loader>`
+
+Additionally, the Symfony Class Loader Component ships with a set of wrapper
+classes which can be used to add additional functionality on top of existing
+autoloaders:
+
+* :doc:`cache_class_loader`
+
+* :doc:`debug_class_loader`
+
+Installation
+------------
+
+You can install the component in 2 different ways:
+
+* Use the official Git repository (https://github.com/symfony/ClassLoader);
+* :doc:`Install it via Composer </components/using_components>` (``symfony/class-loader``
+  on `Packagist`_).
+
+.. _Packagist: https://packagist.org/packages/symfony/class-loader

components/class_loader/map_class_loader.rst

@@ -0,0 +1,28 @@
+.. index::
+    single: Class Loader; MapClassLoader
+
+MapClassLoader
+==============
+
+Additionally to any dynamic class loader (like the :doc:`PSR-0 class loader <class_loader>`)
+you can use the :class:`Symfony\\Component\\ClassLoader\\MapClassLoader` to statically
+map classes to files. Using it is as easy as passing your mapping to its constructor
+when creating an instance of the ``MapClassLoader`` class::
+
+    require_once '/path/to/src/Symfony/Component/ClassLoader/MapClassLoader';
+
+    $mapping = array(
+        'Foo' => '/path/to/Foo',
+        'Bar' => '/path/to/Bar',
+    );
+
+    $loader = new MapClassLoader($mapping);
+
+    $loader->register();
+
+.. note::
+
+    The default behavior is to append the ``MapClassLoader`` on the autoload
+    stack. If you want to use it as the default autoloader, pass ``true``
+    when calling the ``register()`` method. Your class loader will then be
+    prepended on the autoload stack.

components/index.rst

@@ -5,7 +5,7 @@ The Components
     :hidden:
 
     using_components
-    class_loader
+    class_loader/index
     config/index
     console/index
     css_selector