Class Loading
=============

Class loading is an essential part of any PHP application that
makes heavy use of classes and interfaces. Unfortunately, a lot of
people and projects spend a lot of time and effort on custom and
specialized class loading strategies. It can quickly become a pain
to understand what is going on when using multiple libraries and/or
frameworks, each with its own way to do class loading. Class
loading should be simple and it is an ideal candidate for
convention over configuration.

Overview
--------

The Doctrine Common ClassLoader implements a simple and efficient
approach to class loading that is easy to understand and use. The
implementation is based on the widely used and accepted convention
of mapping namespace and class names to a directory structure. This
approach is used for example by Symfony2, the Zend Framework and of
course, Doctrine.

For example, the following class:

.. code-block:: php

    <?php
    namespace MyProject\Shipping;
    class ShippingStrategy { ... }

resides in the following directory structure:

::

    src/
      /MyProject
        /Shipping
           ShippingStrategy.php

Note that the name of "src" or the structure above or beside this
directory is completely arbitrary. "src" could be named "classes"
or "lib" or whatever. The only convention to adhere to is to map
namespaces to directories and classes to files named after the
class name.

Usage
-----

To use a Doctrine Common ClassLoader, you first need to load the
class file containing the ClassLoader. This is the only class file
that actually needs to be loaded explicitly via ``require``. All
other classes will be loaded on demand by the configured class
loaders.

.. code-block:: php

    <?php
    use Doctrine\Common\ClassLoader;
    require '/path/to/Doctrine/Common/ClassLoader.php';
    $classLoader = new ClassLoader('MyProject', '/path/to/src');

A ``ClassLoader`` takes two constructor parameters, both optional.
In the normal case both arguments are supplied. The first argument
specifies the namespace prefix this class loader should be
responsible for and the second parameter is the path to the root
directory where the classes can be found according to the
convention mentioned previously.

The class loader in the example above would thus be responsible for
all classes under the 'MyProject' namespace and it would look for
the class files starting at the directory '/path/to/src'.

Also note that the prefix supplied in the first argument need not
be a root namespace but can be an arbitrarily nested namespace as
well. This allows you to even have the sources of subnamespaces
split across different directories. For example, all projects under
the Doctrine umbrella reside in the Doctrine namespace, yet the
sources for each project usually do not reside under a common root
directory. The following is an example of configuring three class
loaders, one for each used Doctrine project:

.. code-block:: php

    <?php
    use Doctrine\Common\ClassLoader;
    require '/path/to/Doctrine/Common/ClassLoader.php';
    $commonLoader = new ClassLoader('Doctrine\Common', '/path/to/common/lib');
    $dbalLoader = new ClassLoader('Doctrine\DBAL', '/path/to/dbal/lib');
    $ormLoader = new ClassLoader('Doctrine\ORM', '/path/to/orm/lib');
    $commonLoader->register();
    $dbalLoader->register();
    $ormLoader->register();

Do not be afraid of using multiple class loaders. Due to the
efficient class loading design you will not incur much overhead
from using many class loaders. Take a look at the implementation of
``ClassLoader#loadClass`` to see how simple and efficient the class
loading is. The iteration over the installed class loaders happens
in C (with the exception of using ``ClassLoader::classExists``).

A ClassLoader can be used in the following other variations,
however, these are rarely used/needed:


-  If only the second argument is not supplied, the class loader
   will be responsible for the namespace prefix given in the first
   argument and it will rely on the PHP include_path.

-  If only the first argument is not supplied, the class loader
   will be responsible for *all* classes and it will try to look up
   *all* classes starting at the directory given as the second
   argument.

-  If both arguments are not supplied, the class loader will be
   responsible for *all* classes and it will rely on the PHP
   include_path.


File Extension
--------------

By default, a ClassLoader uses the ``.php`` file extension for all
class files. You can change this behavior, for example to use a
ClassLoader to load classes from a library that uses the
".class.php" convention (but it must nevertheless adhere to the
directory structure convention!):

.. code-block:: php

    <?php
    $customLoader = new ClassLoader('CustomLib', '/path/to/custom/lib');
    $customLoader->setFileExtension('.class.php');
    $customLoader->register();

Namespace Separator
-------------------

By default, a ClassLoader uses the ``\`` namespace separator. You
can change this behavior, for example to use a ClassLoader to load
legacy Zend Framework classes that still use the underscore "_"
separator:

.. code-block:: php

    <?php
    $zend1Loader = new ClassLoader('Zend', '/path/to/zend/lib');
    $zend1Loader->setNamespaceSeparator('_');
    $zend1Loader->register();

Failing Silently and class_exists
----------------------------------

A lot of class/autoloaders these days try to fail silently when a
class file is not found. For the most part this is necessary in
order to support using ``class_exists('ClassName', true)`` which is
supposed to return a boolean value but triggers autoloading. This
is a bad thing as it basically forces class loaders to fail
silently, which in turn requires costly file_exists or fopen calls
for each class being loaded, even though in at least 99% of the
cases this is not necessary (compare the number of
class_exists(..., true) invocations to the total number of classes
being loaded in a request).

The Doctrine Common ClassLoader does not fail silently, by design.
It therefore does not need any costly checks for file existence. A
ClassLoader is always responsible for all classes with a certain
namespace prefix and if a class is requested to be loaded and can
not be found this is considered to be a fatal error. This also
means that using class_exists(..., true) to check for class
existence when using a Doctrine Common ClassLoader is not possible
but this is not a bad thing. What class\_exists(..., true) actually
means is two things: 1) Check whether the class is already
defined/exists (i.e. class_exists(..., false)) and if not 2) check
whether a class file can be loaded for that class. In the Doctrine
Common ClassLoader the two responsibilities of loading a class and
checking for its existence are separated, which can be observed by
the existence of the two methods ``loadClass`` and
``canLoadClass``. Thereby ``loadClass`` does not invoke
``canLoadClass`` internally, by design. However, you are free to
use it yourself to check whether a class can be loaded and the
following code snippet is thus equivalent to class\_exists(...,
true):

.. code-block:: php

    <?php
    // Equivalent to if (
    ('Foo', true)) if there is only 1 class loader to check
    if (class_exists('Foo', false) || $classLoader->canLoadClass('Foo')) {
      // ...
    }

The only problem with this is that it is inconvenient as you need
to have a reference to the class loaders around (and there are
often multiple class loaders in use). Therefore, a simpler
alternative exists for the cases in which you really want to ask
all installed class loaders whether they can load the class:
``ClassLoader::classExists($className)``:

.. code-block:: php

    <?php
    // Equivalent to if (class_exists('Foo', true))
    if (ClassLoader::classExists('Foo')) {
      // ...
    }

This static method can basically be used as a drop-in replacement
for class_exists(..., true). It iterates over all installed class
loaders and asks each of them via ``canLoadClass``, returning early
(with TRUE) as soon as one class loader returns TRUE from
``canLoadClass``. If this sounds like it can potentially be rather
costly then because that is true but it is exactly the same thing
that class_exists(..., true) does under the hood, it triggers a
complete interaction of all class/auto loaders. Checking for class
existence via invoking autoloading was never a cheap thing to do
but now it is more obvious and more importantly, this check is no
longer interleaved with regular class loading, which avoids having
to check each and every class for existence prior to loading it.
The vast majority of classes to be loaded are *not* optional and a
failure to load such a class is, and should be, a fatal error. The
ClassLoader design reflects this.

If you have code that requires the usage of class\_exists(...,
true) or ClassLoader::classExists during normal runtime of the
application (i.e. on each request) try to refactor your design to
avoid it.

Summary
-------

No matter which class loader you prefer to use (Doctrine classes do
not care about how they are loaded), we kindly encourage you to
adhere to the simple convention of mapping namespaces and class
names to a directory structure.

Class loading should be simple, automated and uniform. Time is
better invested in actual application development than in designing
special directory structures, autoloaders and clever caching
strategies for class loading.