<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.loader.load">
    <title>Dynamisches Laden von Dateien und Klassen</title>

    <para>
        Die <classname>Zend_Loader</classname> Klasse enthält Methoden die helfen Dateien dynamisch
        zu laden.
    </para>

    <tip>
        <title>Zend_Loader vs. require_once()</title>

        <para>
            Die <classname>Zend_Loader</classname> Methoden werden am Besten verwendet wenn der
            Dateiname der Verwendet wird variabel ist. Wenn er zum Beispiel auf einem Parameter
            einer Benutzereinfabe oder eines Arguments einer Methode basiert. Wenn
            eine Datei oder eine Klasse geladen werden soll deren Name konstant ist,
            gibt es keinen Vorteil durch die Verwendung von <classname>Zend_Loader</classname>
            gegenüber traditionellen <acronym>PHP</acronym> Funktionen wie <ulink
                url="http://php.net/require_once"><methodname>require_once()</methodname></ulink>.
        </para>
    </tip>

    <sect2 id="zend.loader.load.file">
        <title>Dateien laden</title>

        <para>
            Die statische Methode <methodname>Zend_Loader::loadFile()</methodname> lädt eine
            <acronym>PHP</acronym> Datei. Die geladene Datei kann jeden <acronym>PHP</acronym> Code
            enthalten. Diese Methode ist ein Wrapper für die <acronym>PHP</acronym> Funktion
            <ulink url="http://php.net/include"><methodname>include()</methodname></ulink>.
            Diese Methode gibt bei einem Fehler ein boosches <constant>FALSE</constant> zurück,
            zum Beispiel wenn die definierte Datei nicht existiert.
        </para>

        <example id="zend.loader.load.file.example">
            <title>Beispiel der loadFile() Methode</title>

            <programlisting language="php"><![CDATA[
Zend_Loader::loadFile($filename, $dirs=null, $once=false);
]]></programlisting>
        </example>

        <para>
            Das <varname>$filename</varname> Argument definert den Dateinamen der geladen
            werden soll, und der keine Verzeichnis Informationen enthalten darf.
            Eine Sicherheitsprüfung wird auf <varname>$filename</varname>
            durchgeführt. Das <varname>$filename</varname> Argument darf nur
            Alphanumerische Zeichen enthalten, Bindestriche ("-"), Unterstriche ("_")
            oder Punkte ("."). Das <varname>$dirs</varname> Argument hat keine dieser
            Einschränkungen.
        </para>

        <para>
            Das <varname>$dirs</varname> Argument definiert das Verzeichnis in welchem
            nach der Datei gesucht werden soll. Wenn der Wert <constant>NULL</constant> ist, wird
            nur anhand vom include_path gesucht. Wenn der Wert Zeichenkette oder ein Array ist, wird
            das definierte Verzeichnis oder die Verzeichnisse durchsucht, gefolgt vom
            <property>include_path</property>.
        </para>

        <para>
            Das <varname>$once</varname> Argument ist Boolean. Wenn es <constant>TRUE</constant>
            ist, verwendet <methodname>Zend_Loader::loadFile()</methodname> die
            <acronym>PHP</acronym> Funktion <ulink
                url="http://php.net/include"><methodname>include_once()</methodname></ulink>
            für das Laden der Datei, andernfalls wird die <acronym>PHP</acronym> Funktion
            <ulink url="http://php.net/include_once"><methodname>include()</methodname></ulink>
            verwendet.
        </para>
    </sect2>

    <sect2 id="zend.loader.load.class">
        <title>Klassen laden</title>

        <para>
            Die statische Methode <methodname>Zend_Loader::loadClass($class, $dirs)</methodname>
            lädt eine <acronym>PHP</acronym> Datei und prüft anschließend ob die Klasse existiert.
        </para>

        <example id="zend.loader.load.class.example">
            <title>Beispiel der loadClass() Methode</title>

            <programlisting language="php"><![CDATA[
Zend_Loader::loadClass('Container_Tree',
    array(
        '/home/production/mylib',
        '/home/production/myapp'
    )
);
]]></programlisting>
        </example>

        <para>
            Die Zeichenkette welche die Klasse definiert, wird in einen relativen Pfad
            umgewandelt durch die Annahme das Verzeichnisse für das OS mit Unterstrichen
            getrennt werden und anfügen von '.php'. Im obigen Beispiel wird für Windows
            'Container_Tree' zu 'Container\\Tree.php'.
        </para>

        <para>
            Wenn <varname>$dirs</varname> eine Zeichenkette oder ein Array ist, durchsucht
            <methodname>Zend_Loader::loadClass()</methodname> die Verzeichnisse in der
            angegebenen Reihenfolge. Die erste passende Datei wird geladen. Wenn die
            Datei in den definierten Verzeichnissen <varname>$dirs</varname> nicht existiert
            wird der <property>include_path</property> der <acronym>PHP</acronym> Umgebung
            durchsucht.
        </para>

        <para>
            Wenn die Datei nicht gefunden wird, oder die Klasse nach dem Laden nicht
            existiert, wirft <methodname>Zend_Loader::loadClass()</methodname> eine
            <classname>Zend_Exception</classname>.
        </para>

        <para>
            <methodname>Zend_Loader::loadFile()</methodname> wird für das Laden verwendet, deswegen
            darf der Klassenname nur Alphanumerische Zeichen, den Bindestrich ('-'),
            den Unterstrich ('_') und den Punkt ('.') enthalten.
        </para>

        <note>
            <title>Klassen von PHP Namespaces laden</title>

            <para>
                Beginnend mit Version 1.10.0 erlaubt Zend Framework das Laden von Klassen aus
                <acronym>PHP</acronym> Namespaces. Diese Unterstützung folgt den gleichen
                Richtlinien und Implementationen wie Sie in der <ulink
                    url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
                Framework Interop Group PSR-0</ulink> Referenz Implementation gefunden werden
                können.
            </para>

            <para>
                Mit dieser Richtlinie werden die folgenden Regeln angewandt:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        Jeder Separator für Namespaces wird zu einem
                        <constant>DIRECTORY_SEPARATOR</constant> konvertiert wenn er vom Dateisystem
                        geladen wird.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Jedes "_" Zeichen im <emphasis>CLASS NAME</emphasis> wird zu einem
                        <constant>DIRECTORY_SEPARATOR</constant> konvertiert. Das "_" Zeichen hat
                        keine spezielle Bedeutung im Namespace.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Dem voll-qualifizierte Namespace und der Klasse wird ".php" angehängt wenn
                        Sie vom Dateisystem geladen werden.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Als Beispiel:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package_name\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
                    </para>
                </listitem>
            </itemizedlist>
        </note>
    </sect2>

    <sect2 id="zend.loader.load.isreadable">
        <title>Testen ob eine Datei gelesen werden kann</title>

        <para>
            Die statische Methode <methodname>Zend_Loader::isReadable($pathname)</methodname>
            gibt <constant>TRUE</constant> zurück wenn eine Datei im angegebenen Pfadnamen
            existiert und lesbar ist, andernfalls <constant>FALSE</constant>.
        </para>

        <example id="zend.loader.load.isreadable.example">
            <title>Beispiel der isReadable() Methode</title>

            <programlisting language="php"><![CDATA[
if (Zend_Loader::isReadable($filename)) {
    // Mach was mit $filename
}
]]></programlisting>
        </example>

        <para>
            Das <varname>$filename</varname> Argument definiert den Dateinamen der
            geprüft werden soll. Er darf Pfadinformationen enthalten. Diese Methode
            ist ein Wrapper für die <acronym>PHP</acronym> Funktion
            <ulink url="http://php.net/is_readable"><methodname>is_readable()</methodname></ulink>.
            Diese <acronym>PHP</acronym> Funktion durchsucht den <property>include_path</property>
            nicht, während <methodname>Zend_Loader::isReadable()</methodname> dies macht.
        </para>
    </sect2>

    <sect2 id="zend.loader.load.autoload">
        <title>Verwenden von Autoloaders</title>

        <para>
            Die <classname>Zend_Loader</classname> Klasse enthält eine Methode die im
            <acronym>PHP</acronym> SPL Autoloader registriert werden kann.
            <methodname>Zend_Loader::autoload()</methodname> ist die Callback Methode. Als
            Vereinfachung bietet <classname>Zend_Loader</classname> die
            <methodname>registerAutoload()</methodname> Funktion welche die
            <methodname>autoload()</methodname> Methode registriert. Wenn die
            <property>spl_autoload</property> Erweiterung in der <acronym>PHP</acronym> Umgebung
            nicht vorhanden ist wird die <methodname>registerAutoload()</methodname> Methode eine
            <classname>Zend_Exception</classname> werfen.
        </para>

        <example id="zend.loader.load.autoload.example">
            <title>Beispiel für das registrieren der Autoloader Callback Methode</title>

            <programlisting language="php"><![CDATA[
Zend_Loader::registerAutoload();
]]></programlisting>
        </example>

        <para>
            Nach dem registrieren des Zend Framework Autoload Callbacks, können
            die Klassen des Zend Frameworks referenziert werden ohne das sie
            explizit geladen werden müssen. Die <methodname>autoload()</methodname> Methode
            verwendet automatisch <methodname>Zend_Loader::loadClass()</methodname> wenn eine
            Klasse referenziert wird.
        </para>

        <para>
            Wenn die <classname>Zend_Loader</classname> Klasse erweitert wird, kann ein optionales
            Argument für <methodname>registerAutoload()</methodname> angegeben werden, um die Klasse
            zu definieren von welcher die <methodname>autoload()</methodname> Methode registriert
            werden soll.
        </para>

        <example id="zend.loader.load.autoload.example-extended">
            <title>
                Beispiel für das registrieren der Autoload Callback Methode von einer
                erweiterten Klasse
            </title>

            <para>
                Wegen der Semantik der Referenzen von statischen Funktionen in
                <acronym>PHP</acronym>, muß Code für beide <methodname>loadClass()</methodname> und
                <methodname>autoload()</methodname> implementiert werden, und
                <methodname>autoload()</methodname> muß <methodname>self::loadClass()</methodname>
                aufrufen. Wenn die <methodname>autoload()</methodname> Methode den Aufruf zu
                <methodname>self::loadClass()</methodname> an die Elternklasse delegiert, ruft Sie
                die Methode des Namens in der Elternklasse und nicht in der Subklasse auf.
            </para>

            <programlisting language="php"><![CDATA[
class My_Loader extends Zend_Loader
{
    public static function loadClass($class, $dirs = null)
    {
        parent::loadClass($class, $dirs);
    }

    public static function autoload($class)
    {
        try {
            self::loadClass($class);
            return $class;
        } catch (Exception $e) {
            return false;
        }
    }
}

Zend_Loader::registerAutoload('My_Loader');
]]></programlisting>
        </example>

        <para>
            Der Callback für den Autoloader kann entfernt werden. Die
            <methodname>registerAutoload()</methodname> Methode hat ein zweites optionales Argument
            welches standardmäßig <constant>TRUE</constant> ist. Wenn dieses Argument
            <constant>FALSE</constant> ist, wird die Registrierung des Callback des Autoloaders vom
            SPL Autoload Stack entfernt.
        </para>
    </sect2>
</sect1>