diff --git a/book/http_fundamentals.rst b/book/http_fundamentals.rst index 8ead7a1299b..6bc0e6d1970 100644 --- a/book/http_fundamentals.rst +++ b/book/http_fundamentals.rst @@ -520,7 +520,7 @@ regardless of how your project is developed. To name a few: * `Validator`_ A system for creating rules about data and then validating whether or not user-submitted data follows those rules; -* :doc:`ClassLoader` An autoloading library that allows +* :doc:`ClassLoader` An autoloading library that allows PHP classes to be used without needing to manually ``require`` the files containing those classes; diff --git a/components/class_loader.rst b/components/class_loader.rst deleted file mode 100644 index eb64f41dbbe..00000000000 --- a/components/class_loader.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. index:: - pair: Autoloader; Configuration - single: Components; ClassLoader - -The ClassLoader Component -========================= - - The ClassLoader Component loads your project classes automatically if they - follow some standard PHP conventions. - -Whenever you use an undefined class, PHP uses the autoloading mechanism to -delegate the loading of a file defining the class. Symfony2 provides a -"universal" autoloader, which is able to load classes from files that -implement one of the following conventions: - -* The technical interoperability `standards`_ for PHP 5.3 namespaces and class - names; - -* The `PEAR`_ naming convention for classes. - -If your classes and the third-party libraries you use for your project follow -these standards, the Symfony2 autoloader is the only autoloader you will ever -need. - -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 ` (``symfony/class-loader`` on `Packagist`_). - -Usage ------ - -.. versionadded:: 2.1 - The ``useIncludePath`` method was added in Symfony 2.1. - -Registering the :class:`Symfony\\Component\\ClassLoader\\UniversalClassLoader` -autoloader is straightforward:: - - require_once '/path/to/src/Symfony/Component/ClassLoader/UniversalClassLoader.php'; - - use Symfony\Component\ClassLoader\UniversalClassLoader; - - $loader = new UniversalClassLoader(); - - // You can search the include_path as a last resort. - $loader->useIncludePath(true); - - // ... register namespaces and prefixes here - see below - - $loader->register(); - -For minor performance gains class paths can be cached in memory using APC by -registering the :class:`Symfony\\Component\\ClassLoader\\ApcUniversalClassLoader`:: - - require_once '/path/to/src/Symfony/Component/ClassLoader/UniversalClassLoader.php'; - require_once '/path/to/src/Symfony/Component/ClassLoader/ApcUniversalClassLoader.php'; - - use Symfony\Component\ClassLoader\ApcUniversalClassLoader; - - $loader = new ApcUniversalClassLoader('apc.prefix.'); - $loader->register(); - -The autoloader is useful only if you add some libraries to autoload. - -.. note:: - - The autoloader is automatically registered in a Symfony2 application (see - ``app/autoload.php``). - -If the classes to autoload use namespaces, use the -:method:`Symfony\\Component\\ClassLoader\\UniversalClassLoader::registerNamespace` -or -:method:`Symfony\\Component\\ClassLoader\\UniversalClassLoader::registerNamespaces` -methods:: - - $loader->registerNamespace('Symfony', __DIR__.'/vendor/symfony/symfony/src'); - - $loader->registerNamespaces(array( - 'Symfony' => __DIR__.'/../vendor/symfony/symfony/src', - 'Monolog' => __DIR__.'/../vendor/monolog/monolog/src', - )); - - $loader->register(); - -For classes that follow the PEAR naming convention, use the -:method:`Symfony\\Component\\ClassLoader\\UniversalClassLoader::registerPrefix` -or -:method:`Symfony\\Component\\ClassLoader\\UniversalClassLoader::registerPrefixes` -methods:: - - $loader->registerPrefix('Twig_', __DIR__.'/vendor/twig/twig/lib'); - - $loader->registerPrefixes(array( - 'Swift_' => __DIR__.'/vendor/swiftmailer/swiftmailer/lib/classes', - 'Twig_' => __DIR__.'/vendor/twig/twig/lib', - )); - - $loader->register(); - -.. note:: - - Some libraries also require their root path be registered in the PHP - include path (``set_include_path()``). - -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->registerNamespaces(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', - )); - - $loader->register(); - -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. - -.. _standards: http://symfony.com/PSR0 -.. _PEAR: http://pear.php.net/manual/en/standards.php -.. _Packagist: https://packagist.org/packages/symfony/class-loader diff --git a/components/class_loader/cache_class_loader.rst b/components/class_loader/cache_class_loader.rst new file mode 100644 index 00000000000..550968c778d --- /dev/null +++ b/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 diff --git a/components/class_loader/class_loader.rst b/components/class_loader/class_loader.rst new file mode 100644 index 00000000000..390ef5161d8 --- /dev/null +++ b/components/class_loader/class_loader.rst @@ -0,0 +1,87 @@ +.. index:: + single: Class Loader; PSR-0 Class Loader + +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, you +can use the :class:`Symfony\\Component\\ClassLoader\\ClassLoader` class to +load all of your project's classes. + +.. tip:: + + You can use both the ``ApcClassLoader`` and the ``XcacheClassLoader`` to + :doc:`cache ` a ``ClassLoader`` + instance or the ``DebugClassLoader`` to :doc:`debug ` + 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 diff --git a/components/class_loader/debug_class_loader.rst b/components/class_loader/debug_class_loader.rst new file mode 100644 index 00000000000..c861afcc7d4 --- /dev/null +++ b/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(); diff --git a/components/class_loader/index.rst b/components/class_loader/index.rst new file mode 100644 index 00000000000..7538957fc65 --- /dev/null +++ b/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 diff --git a/components/class_loader/introduction.rst b/components/class_loader/introduction.rst new file mode 100644 index 00000000000..0f905e7a228 --- /dev/null +++ b/components/class_loader/introduction.rst @@ -0,0 +1,36 @@ +.. index:: + single: Components; Class Loader + +The Class Loader Component +========================== + + The Class Loader Component provides tools to load and cache your project + classes automatically. + +Usage +----- + +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 ` +* :doc:`Load classes based on class-to-file mapping ` + +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:`/components/class_loader/cache_class_loader` +* :doc:`/components/class_loader/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 ` (``symfony/class-loader`` + on `Packagist`_). + +.. _Packagist: https://packagist.org/packages/symfony/class-loader diff --git a/components/class_loader/map_class_loader.rst b/components/class_loader/map_class_loader.rst new file mode 100644 index 00000000000..12b1791e9bd --- /dev/null +++ b/components/class_loader/map_class_loader.rst @@ -0,0 +1,40 @@ +.. index:: + single: Class Loader; MapClassLoader + +MapClassLoader +============== + +Introduction +------------ + +Additionally to any dynamic class loader (like the +:doc:`PSR-0 class loader `) you can use +the :class:`Symfony\\Component\\ClassLoader\\MapClassLoader` to statically map +classes to files. This is useful if you use third-party libraries which don't +follow the `PSR-0`_ standards. + +Usage +----- + +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. + +.. _PSR-0: http://symfony.com/PSR0 diff --git a/components/index.rst b/components/index.rst index 865b2b274e6..e1b11dbb942 100644 --- a/components/index.rst +++ b/components/index.rst @@ -5,7 +5,7 @@ The Components :hidden: using_components - class_loader + class_loader/index config/index console/index css_selector diff --git a/components/map.rst.inc b/components/map.rst.inc index acd892e0c67..9f507aa5cdc 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -1,8 +1,12 @@ * :doc:`/components/using_components` -* **Class Loader** +* :doc:`/components/class_loader/index` - * :doc:`/components/class_loader` + * :doc:`/components/class_loader/introduction` + * :doc:`/components/class_loader/class_loader` + * :doc:`/components/class_loader/map_class_loader` + * :doc:`/components/class_loader/cache_class_loader` + * :doc:`/components/class_loader/debug_class_loader` * :doc:`/components/config/index` diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst index 30cffa72fb3..bce41d873a8 100644 --- a/quick_tour/the_architecture.rst +++ b/quick_tour/the_architecture.rst @@ -68,7 +68,7 @@ in your projects. .. note:: If you want to learn more about Composer's autoloader, read `Composer-Autoloader`_. - Symfony also has an autoloading component - read ":doc:`/components/class_loader`". + Symfony also has an autoloading component - read ":doc:`/components/class_loader/class_loader`". Understanding the Bundle System -------------------------------