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 "<filename>.php</filename>" is added. For
            example, the class "<classname>Foo_Bar_Baz</classname>" would correspond to
            "<filename>Foo/Bar/Baz.php</filename>" on the filesystem. The assumption is also
            that the classes may be resolved via <acronym>PHP</acronym>'s
            <property>include_path</property> setting, which allows both
            <methodname>include()</methodname> and <methodname>require()</methodname> to find
            the filename via a relative path lookup on the <property>include_path</property>.
        </para>

        <para>
            Additionally, per <acronym>PEAR</acronym> 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 <acronym>PHP</acronym>'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>Provide namespace matching</emphasis>. If the class
                    namespace prefix is not in a list of registered namespaces, return
                    <constant>FALSE</constant> immediately. This allows for more optimistic
                    matching, as well as fallback to other autoloaders.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>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>Allow toggling error suppression</emphasis>. We feel -- and the
                    greater <acronym>PHP</acronym> 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>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 Zend Framework's mechanisms.
                    <classname>Zend_Loader_Autoloader</classname> allows specyfing an alternate
                    callback for autoloading.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Allow manipulation of the <acronym>SPL</acronym> 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 Zend Framework autoloader.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>