Permalink
Browse files

feature #4081 [Components][ClassLoader] documentation for the ClassMa…

…pGenerator class (xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[Components][ClassLoader] documentation for the ClassMapGenerator class

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#2471)
| Applies to    | all
| Fixed tickets | #1134

Commits
-------

2ebe6c3 documentation for the ClassMapGenerator class
  • Loading branch information...
weaverryan committed Aug 15, 2014
2 parents 12d0b82 + 2ebe6c3 commit 41116dae3d9e34852cc3ef5e105d23f5c1f67c63
Showing with 128 additions and 1 deletion.
  1. +125 −0 components/class_loader/class_map_generator.rst
  2. +2 −1 components/class_loader/index.rst
  3. +1 −0 components/map.rst.inc
@@ -0,0 +1,125 @@
.. index::
single: Autoloading; Class Map Generator
single: ClassLoader; Class Map Generator
The Class Map Generator
=======================
Loading a class usually is an easy task given the `PSR-0`_ and `PSR-4`_ standards.
Thanks to the Symfony ClassLoader component or the autoloading mechanism provided
by Composer, you don't have to map your class names to actual PHP files manually.
Nowadays, PHP libraries usually come with autoloading support through Composer.
But from time to time you may have to use a third-party library that comes
without any autoloading support and therefore forces you to load each class
manually. For example, imagine a library with the following directory structure:
.. code-block:: text
library/
├── bar/
│   ├── baz/
│   │   └── Boo.php
│   └── Foo.php
└── foo/
├── bar/
│   └── Foo.php
└── Bar.php
These files contain the following classes:
=========================== ================
File Class name
=========================== ================
``library/bar/baz/Boo.php`` ``Acme\Bar\Baz``
--------------------------- ----------------
``library/bar/Foo.php`` ``Acme\Bar``
--------------------------- ----------------
``library/foo/bar/Foo.php`` ``Acme\Foo\Bar``
--------------------------- ----------------
``library/foo/Bar.php`` ``Acme\Foo``
=========================== ================
To make your life easier, the ClassLoader component comes with a
:class:`Symfony\\Component\\ClassLoader\\ClassMapGenerator` class that makes
it possible to create a map of class names to files.
Generating a Class Map
----------------------
To generate the class map, simply pass the root directory of your class files
to the :method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::createMap``
method::
use Symfony\Component\ClassLoader\ClassMapGenerator;
print_r(ClassMapGenerator::createMap(__DIR__.'/library'));
Given the files and class from the table above, you should see an output like
this:
.. code-block:: text
Array
(
[Acme\Foo] => /var/www/library/foo/Bar.php
[Acme\Foo\Bar] => /var/www/library/foo/bar/Foo.php
[Acme\Bar\Baz] => /var/www/library/bar/baz/Boo.php
[Acme\Bar] => /var/www/library/bar/Foo.php
)
Dumping the Class Map
---------------------
Writing the class map to the console output is not really sufficient when
it comes to autoloading. Luckily, the ``ClassMapGenerator`` provides the
:method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::dump` method
to save the generated class map to the filesystem::
use Symfony\Component\ClassLoader\ClassMapGenerator;
ClassMapGenerator::dump(__DIR__.'/library', __DIR__.'/class_map.php');
This call to ``dump()`` generates the class map and writes it to the ``class_map.php``
file in the same directory with the following contents::
<?php return array (
'Acme\\Foo' => '/var/www/library/foo/Bar.php',
'Acme\\Foo\\Bar' => '/var/www/library/foo/bar/Foo.php',
'Acme\\Bar\\Baz' => '/var/www/library/bar/baz/Boo.php',
'Acme\\Bar' => '/var/www/library/bar/Foo.php',
);
Instead of loading each file manually, you'll only have to register the generated
class map with, for example, the :class:`Symfony\\Component\\ClassLoader\\MapClassLoader`::
use Symfony\Component\ClassLoader\MapClassLoader;
$mapping = include __DIR__.'/class_map.php';
$loader = new MapClassLoader($mapping);
$loader->register();
// you can now use the classes:
use Acme\Foo;
$foo = new Foo();
// ...
.. note::
The example assumes that you already have autoloading working (e. g.
through `Composer`_ or one of the other class loaders from the ClassLoader
component.
Besides dumping the class map for one directory, you can also pass an array
of directories for which to generate the class map (the result actually is
the same as in the example above)::
use Symfony\Component\ClassLoader\ClassMapGenerator;
ClassMapGenerator::dump(array(__DIR__.'/library/bar', __DIR__.'/library/foo'), __DIR__.'/class_map.php');
.. _`PSR-0`: http://www.php-fig.org/psr/psr-0
.. _`PSR-4`: http://www.php-fig.org/psr/psr-4
.. _`Composer`: http://getcomposer.org
@@ -3,9 +3,10 @@ ClassLoader
.. toctree::
:maxdepth: 2
introduction
class_loader
map_class_loader
cache_class_loader
debug_class_loader
class_map_generator
@@ -7,6 +7,7 @@
* :doc:`/components/class_loader/map_class_loader`
* :doc:`/components/class_loader/cache_class_loader`
* :doc:`/components/class_loader/debug_class_loader`
* :doc:`/components/class_loader/class_map_generator`
* :doc:`/components/config/index`

0 comments on commit 41116da

Please sign in to comment.