repo_zf1/documentation/manual/en/tutorials/autoloading-design.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="learning.autoloading.design">
    <title>Goals and Design</title>

    <sect2 id="learning.autoloading.design.naming">
        <title>Class Naming Conventions</title>

        <para>
            To understand autoloading in Zend Framework, first you need to understand the relationship
            between class names and class files.
        </para>

        <para>
            Zend Framework has borrowed an idea from <ulink url="http://pear.php.net/">PEAR</ulink>,
            whereby class names have a 1:1 relationship with the filesystem. Simply put, the underscore
            character ("_") is replaced by a directory separator in order to resolve the path to the
            file, and then the suffix ".php" is added. For example, the class "Foo_Bar_Baz" would
            correspond to "Foo/Bar/Baz.php" on the filesystem. The assumption is also that the classes
            may be resolved via PHP's <constant>include_path</constant> setting, which allows both
            <methodname>include</methodname> and <methodname>require</methodname> to find the filename
            via a relative path lookup on the <constant>include_path</constant>.
        </para>

        <para>
            Additionally, per PEAR as well as the <ulink
                url="http://php.net/userlandnaming.tips">PHP project</ulink>, we use and recommend
            using a vendor or project prefix for your code. What this means is that all classes you
            write will share a common class prefix; for example, all code in Zend Framework has the
            prefix "Zend_". This naming convention helps prevent naming collisions. Within Zend
            Framework, we often refer to this as the "namespace" prefix; be careful not to confuse
            it with PHP's native namespace implementation.
        </para>

        <para>
            Zend Framework follows these simple rules internally, and our coding standards encourage
            that you do so as well for all library code.
        </para>
    </sect2>

    <sect2 id="learning.autoloading.design.autoloader">
        <title>Autoloader Conventions and Design</title>

        <para>
            Zend Framework's autoloading support, provided primarily via
            <classname>Zend_Loader_Autoloader</classname>, has the following goals and design elements:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis role="strong">Provide namespace matching.</emphasis> If the class
                    namespace prefix is not in a list of registered namespaces, return false
                    immediately. This allows for more optimistic matching, as well as fallback to other
                    autoloaders.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">Allow the autoloader to act as a fallback
                        autoloader.</emphasis> In the case where a team may be widely distributed, or
                    using an undetermined set of namespace prefixes, the autoloader should still be
                    configurable such that it will attempt to match any namespace prefix. It will be
                    noted, however, that this practice is not recommended, as it can lead to unnecessary
                    lookups.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">Allow toggling error suppression.</emphasis> We feel -- and
                    the greater PHP community does as well -- that error suppression is a bad idea. It's
                    expensive, and it masks very real application problems. So, by default, it should be
                    off. However, if a developer <emphasis>insists</emphasis> that it be on, we allow
                    toggling it on.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">Allow specifying custom callbacks for
                        autoloading.</emphasis> Some developers don't want to use
                    <methodname>Zend_Loader::loadClass()</methodname> for autoloading, but still want to
                    make use of ZF's mechanisms. <classname>Zend_Loader_Autoloader</classname> allows
                    specyfing an alternate callback for autoloading.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">Allow manipulation of the SPL autoload callback
                        chain.</emphasis> The purpose of this is to allow specifying additional
                    autoloaders -- for instance, resource loaders for classes that don't have a 1:1
                    mapping to the filesystem -- to be registered before or after the primary ZF
                    autoloader.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>