Skip to content

Commit 997cd57

Browse files
weaverryanweaverryan
committed
Merge pull request #2913 from xabbuh/issue-2834
documentation for the Class Loader component
2 parents 4c86c56 + f162f3e commit 997cd57

11 files changed

+280
-134
lines changed

‎book/http_fundamentals.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -527,7 +527,7 @@ regardless of how your project is developed. To name a few:
527527
* `Validator`_ A system for creating rules about data and then validating
528528
whether or not user-submitted data follows those rules;
529529

530-
* :doc:`ClassLoader</components/class_loader>` An autoloading library that allows
530+
* :doc:`ClassLoader</components/class_loader/introduction>` An autoloading library that allows
531531
PHP classes to be used without needing to manually ``require`` the files
532532
containing those classes;
533533

‎components/class_loader.rst

-129
This file was deleted.

‎components/class_loader/cache_class_loader.rst

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
.. index::
2+
single: APC; ApcClassLoader
3+
single: Class Loader; ApcClassLoader
4+
single: Class Loader; Cache
5+
single: Class Loader; XcacheClassLoader
6+
single: XCache; XcacheClassLoader
7+
8+
Cache a Class Loader
9+
====================
10+
11+
Introduction
12+
------------
13+
14+
Finding the file for a particular class can be an expensive task. Luckily,
15+
the Class Loader Component comes with two classes to cache the mapping
16+
from a class to its containing file. Both the :class:`Symfonfy\\Component\\ClassLoader\\ApcClassLoader`
17+
and the :class:`Symfony\\Component\\ClassLoader\\XcacheClassLoader` wrap
18+
around an object which implements a ``findFile()`` method to find the file
19+
for a class.
20+
21+
.. note::
22+
23+
Both the ``ApcClassLoader`` and the ``XcacheClassLoader`` can be used
24+
to cache Composer's `autoloader`_.
25+
26+
ApcClassLoader
27+
--------------
28+
29+
.. versionadded:: 2.1
30+
The ``ApcClassLoader`` class was added in Symfony 2.1.
31+
32+
``ApcClassLoader`` wraps an existing class loader and caches calls to its
33+
``findFile()`` method using `APC`_::
34+
35+
require_once '/path/to/src/Symfony/Component/ClassLoader/ApcClassLoader.php';
36+
37+
// instance of a class that implements a findFile() method
38+
$loader = ...;
39+
40+
// my_prefix is the APC namespace prefix to use
41+
$cachedLoader = new ApcClassLoader('my_prefix', $loader);
42+
43+
// register the cached class loader
44+
$cachedLoader->register();
45+
46+
// eventually deactivate the non-cached loader if it was registered
47+
// previously
48+
$loader->unregister();
49+
50+
XcacheClassLoader
51+
-----------------
52+
53+
.. versionadded:: 2.1
54+
The ``XcacheClassLoader`` class was added in Symfony 2.1.
55+
56+
``XcacheClassLoader`` uses `XCache`_ to cache a class loader. Registering
57+
it is straightforward::
58+
59+
require_once '/path/to/src/Symfony/Component/ClassLoader/XcacheClassLoader.php';
60+
61+
// instance of a class that implements a findFile() method
62+
$loader = ...;
63+
64+
// my_prefix is the XCache namespace
65+
$cachedLoader = new XcacheClassLoader('my_prefix', $loader);
66+
67+
// register the cached class loader
68+
$cachedLoader->register();
69+
70+
// eventually deactivate the non-cached loader if it was registered
71+
// previously
72+
$loader->unregister();
73+
74+
.. _APC: http://php.net/manual/en/book.apc.php
75+
.. _autoloader: http://getcomposer.org/doc/01-basic-usage.md#autoloading
76+
.. _XCache: http://xcache.lighttpd.net

‎components/class_loader/class_loader.rst

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
.. index::
2+
single: Class Loader; PSR-0 Class Loader
3+
4+
The PSR-0 Class Loader
5+
======================
6+
7+
Introduction
8+
------------
9+
10+
.. versionadded:: 2.1
11+
The ``ClassLoader`` class was added in Symfony 2.1.
12+
13+
If your classes and third-party libraries follow the `PSR-0`_ standards, you
14+
can use the :class:`Symfony\\Component\\ClassLoader\\ClassLoader` class to
15+
load all of your project's classes.
16+
17+
.. tip::
18+
19+
You can use both the ``ApcClassLoader`` and the ``XcacheClassLoader`` to
20+
:doc:`cache </components/class_loader/cache_class_loader>` a ``ClassLoader``
21+
instance or the ``DebugClassLoader`` to :doc:`debug </components/class_loader/debug_class_loader>`
22+
it.
23+
24+
Usage
25+
-----
26+
27+
Registering the :class:`Symfony\\Component\\ClassLoader\\ClassLoader` autoloader
28+
is straightforward::
29+
30+
require_once '/path/to/src/Symfony/Component/ClassLoader/ClassLoader.php';
31+
32+
use Symfony\Component\ClassLoader\ClassLoader;
33+
34+
$loader = new ClassLoader();
35+
36+
// to enable searching the include path (eg. for PEAR packages)
37+
$loader->useIncludePath(true);
38+
39+
// ... register namespaces and prefixes here - see below
40+
41+
$loader->register();
42+
43+
.. note::
44+
45+
The autoloader is automatically registered in a Symfony2 application (see
46+
``app/autoload.php``).
47+
48+
Use the :method:`Symfony\\Component\\ClassLoader\\ClassLoader::addPrefix` or
49+
:method:`Symfony\\Component\\ClassLoader\\ClassLoader::addPrefixes` methods to
50+
register your classes::
51+
52+
// register a single namespaces
53+
$loader->addPrefix('Symfony', __DIR__.'/vendor/symfony/symfony/src');
54+
55+
// register several namespaces at once
56+
$loader->addPrefixes(array(
57+
'Symfony' => __DIR__.'/../vendor/symfony/symfony/src',
58+
'Monolog' => __DIR__.'/../vendor/monolog/monolog/src',
59+
));
60+
61+
// register a prefix for a class following the PEAR naming conventions
62+
$loader->addPrefix('Twig_', __DIR__.'/vendor/twig/twig/lib');
63+
64+
$loader->addPrefixes(array(
65+
'Swift_' => __DIR__.'/vendor/swiftmailer/swiftmailer/lib/classes',
66+
'Twig_' => __DIR__.'/vendor/twig/twig/lib',
67+
));
68+
69+
Classes from a sub-namespace or a sub-hierarchy of `PEAR`_ classes can be looked
70+
for in a location list to ease the vendoring of a sub-set of classes for large
71+
projects::
72+
73+
$loader->addPrefixes(array(
74+
'Doctrine\\Common' => __DIR__.'/vendor/doctrine/common/lib',
75+
'Doctrine\\DBAL\\Migrations' => __DIR__.'/vendor/doctrine/migrations/lib',
76+
'Doctrine\\DBAL' => __DIR__.'/vendor/doctrine/dbal/lib',
77+
'Doctrine' => __DIR__.'/vendor/doctrine/orm/lib',
78+
));
79+
80+
In this example, if you try to use a class in the ``Doctrine\Common`` namespace
81+
or one of its children, the autoloader will first look for the class under the
82+
``doctrine-common`` directory, and it will then fallback to the default
83+
``Doctrine`` directory (the last one configured) if not found, before giving up.
84+
The order of the registrations is significant in this case.
85+
86+
.. _PEAR: http://pear.php.net/manual/en/standards.naming.php
87+
.. _PSR-0: http://symfony.com/PSR0

‎components/class_loader/debug_class_loader.rst

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. index::
2+
single: Class Loader; DebugClassLoader
3+
4+
Debugging a Class Loader
5+
========================
6+
7+
.. versionadded:: 2.1
8+
The ``DebugClassLoader`` class was added in Symfony 2.1.
9+
10+
When a class isn't found by the registered autoloaders you can use the
11+
:class:`Symfony\\Component\\ClassLoader\\DebugClassLoader`. All autoloaders
12+
which implement a ``findFile()`` method are replaced with a ``DebugClassLoader``
13+
wrapper. It throws an exception if a file is found but does not declare the
14+
class.
15+
16+
Using the ``DebugClassLoader`` is as easy as calling its static :method:`DebugClassLoader::enable`
17+
method::
18+
19+
use Symfony\Component\ClassLoader\DebugClassLoader;
20+
21+
DebugClassLoader::enable();

‎components/class_loader/index.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Class Loader
2+
============
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
class_loader
9+
map_class_loader
10+
cache_class_loader
11+
debug_class_loader

‎components/class_loader/introduction.rst

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. index::
2+
single: Components; Class Loader
3+
4+
The Class Loader Component
5+
==========================
6+
7+
The Class Loader Component provides tools to load and cache your project
8+
classes automatically.
9+
10+
Usage
11+
-----
12+
13+
Whenever you use an undefined class, PHP uses the autoloading mechanism to
14+
delegate the loading of a file defining the class. Symfony2 provides two
15+
autoloaders, which are able to load your classes:
16+
17+
* :doc:`A PSR-0 class loader </components/class_loader/class_loader>`
18+
* :doc:`Load classes based on class-to-file mapping </components/class_loader/map_class_loader>`
19+
20+
Additionally, the Symfony Class Loader Component ships with a set of wrapper
21+
classes which can be used to add additional functionality on top of existing
22+
autoloaders:
23+
24+
* :doc:`/components/class_loader/cache_class_loader`
25+
* :doc:`/components/class_loader/debug_class_loader`
26+
27+
Installation
28+
------------
29+
30+
You can install the component in 2 different ways:
31+
32+
* Use the official Git repository (https://github.com/symfony/ClassLoader);
33+
* :doc:`Install it via Composer </components/using_components>` (``symfony/class-loader``
34+
on `Packagist`_).
35+
36+
.. _Packagist: https://packagist.org/packages/symfony/class-loader

0 commit comments

Comments
 (0)