repo_zf1/documentation/manual/de/module_specs/Zend_Tool-Extending.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20807 -->
<!-- Reviewed: no -->
<sect1 id="zend.tool.extending">
    <title>Zend_Tool erweitern</title>

    <sect2 id="zend.tool.extending.overview">
        <title>Übersicht über Zend_Tool</title>

        <para>
            <classname>Zend_Tool_Framework</classname> ist ein Framework für die Bereitstellung
            gemeinsamer Funktionalitäten wie die Erstellung von Projekthüllen, Code Erzeugung,
            Erstellung von Suchindezes, und noch mehr. Funktionalitäten können geschrieben und über
            <acronym>PHP</acronym> Klassen in den <acronym>PHP</acronym>
            <property>include_path</property> geworfen werden, was eine immense Flexibilität der
            Implementation liefert. Die Funktionalität kann dann verwendet werden indem eine
            Implementation geschrieben wird oder durch protokoll-spezifische Clients -- wie Konsolen
            Clients, <acronym>XML-RPC</acronym>, <acronym>SOAP</acronym>, und andere.
        </para>

        <para>
            <classname>Zend_Tool_Project</classname> baut auf die Möglichkeiten von
            <classname>Zend_Tool_Framework</classname> auf und erweitert diese um ein "Projekt" zu
            managen. Generell ist ein "Projekt" ein geplantes Ereignis oder eine Initiative. In der
            Computerwelt sind Projekte generell Sammlungen von Ressourcen. Diese Ressourcen können
            Dateien, Verzeichnisse, Datenbanken, Schematas, Bilder, Stile und anderes sein.
        </para>
    </sect2>

    <sect2 id="zend.tool.extending.zend-tool-framework">
        <title>Erweiterungen von Zend_Tool_Framework</title>

        <sect3 id="zend.tool.extending.zend-tool-framework.architecture">
            <title>Überblick der Architektur</title>

            <para>
                <classname>Zend_Tool_Framework</classname> bietet das folgende:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Gemeinsame Interfaces und Abstraktes</emphasis> welche es
                        Entwicklern erlauben Funktionalitäten und Möglichkeiten zu erstellen welche
                        durch Tooling Clients verwendbar sind.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Grundsätzliche Client Funktionalität</emphasis> und eine konkrete
                        Konsolenimplementation welche externe Tools und Interfaces mit
                        <classname>Zend_Tool_Framework</classname> verbindet. Der Konsolenclient
                        kann in <acronym>CLI</acronym> Umgebungen verwendet werden, wie Unix Shells
                        und der Windows Konsole.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>"Provider" und "Manifest" Interfaces</emphasis> welche vom
                        Toolingsystem verwendet werden können. "Provider" repräsentieren den
                        funktionalen Aspekt des Frameworks, und definieren die Aktionen welche
                        Tooling Clients aufrufen können. "Manifests" agieren als Metadaten
                        Registrierungen welche zusätzlichen Kontext für die verschiedenen
                        definierten Provider bieten.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Ein introspektives Ladesystem</emphasis> welches die Umgebung auf
                        Provider scannt und erkennt was benötigt wird um Sie auszuführen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Ein Standardset von System Provider</emphasis> welche dem System
                        erlauben zu melden was die kompletten Möglichkeiten des Systems sind, und
                        ein nützliches Feedback bieten. Das beinhaltet auch ein ausführliches
                        "Hilfe System".
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Definitionen welche man in diesem Handbuch in Bezug auf
                <classname>Zend_Tool_Framework</classname> beachten sollte sind:
            </para>

            <itemizedlist>

                <listitem>
                    <para>
                        <classname>Zend_Tool_Framework</classname> - Der Framework welche die
                        Tooling Möglichkeiten bereitstellt.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Tooling Client</emphasis> - Ein Entwickler-Tool welches sich zum
                        <classname>Zend_Tool_Framework</classname> verbindet und Ihn verwendet.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Client</emphasis> - Das Subsystem von
                        <classname>Zend_Tool_Framework</classname> welches ein Interface
                        bereitstellt so das sich Tooling-Clienten verbinden, und Kommandos abfragen
                        und ausführen können.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Konsolen Client / Kommandozeilen Interface /
                        <filename>zf.php</filename></emphasis> - Der Tooling Client für die
                        Kommandozeile.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Provider</emphasis> - Ein Subsystem und eine Sammlung von
                        eingebauten Funktionalitäten welche der Framework exportiert.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Manifest</emphasis> - Ein Subsystem für die Definition,
                        Organisation, und Verbreitung von Daten welche Provider benötigen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>Zend_Tool_Project</classname> Provider - Ein Set von Providern
                        speziell für die Erstellung und die Wartung von Zend Framework basierenden
                        Projekten.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.tool.extending.zend-tool-framework.cli-client">
            <title>Verstehen des CLI Clients</title>

            <para>
                Das <acronym>CLI</acronym>, oder Kommandozeilen-Tool (intern als das Konsolen-Tool
                bekannt) ist aktuell das primäre Interface für die Bearbeitung von
                <classname>Zend_Tool</classname> Anfragen. Mit dem <acronym>CLI</acronym> Tool
                können Entwickler Tooling-Anfragen im "Kommandozeilen-Fenster" behandeln,
                üblicherweise auch als "Terminal" Fenster bekannt. Diese Umgebung ist in einer *nix
                Umgebung vorherrschend, hat aber auch eine übliche Implementation in Windows mit
                <filename>cmd.exe</filename>, Console2 und mit dem Cygwin Projekt.
            </para>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-general">
                <title>Das CLI Tool vorbereiten</title>

                <para>
                    Um Tooling-Anfragen über den Kommandozeilen-Client auszuführen, muss man zuerst
                    den Client vorbereiten so dass das System den "zf" Befehl ausführen kann. Der
                    Kommandozeilen-Client ist, für alle Wünsche und Zwecke, die Datei
                    <filename>.sh</filename> oder <filename>.bat</filename> welche mit der Zend
                    Framework Distribution bereitgestellt wird. Im Trunk kann er hier gefunden
                    werden: <ulink
                        url="http://framework.zend.com/svn/framework/standard/trunk/bin/">http://framework.zend.com/svn/framework/standard/trunk/bin/</ulink>.
                </para>

                <para>
                    Wie man sehen kann, gibt es 3 Dateien im <filename>/bin/</filename> Verzeichnis:
                    <filename>zf.php</filename>, <filename>zf.sh</filename>, und
                    <filename>zf.bat</filename>. <filename>zf.sh</filename> und
                    <filename>zf.bat</filename> sind Betriebssystem-spezifische Client-Wrapper:
                    <filename>zf.sh</filename> für die *nix Umgebung, und
                    <filename>zf.bat</filename> für die Win32 Umgebung. Diese Client-Wrapper sind
                    für das Finden der richtigen <filename>php.exe</filename>, das finden der
                    <filename>zf.php</filename>, und die Übergabe an die Anfrage des Clients
                    zuständig. Die <filename>zf.php</filename> ist verantwortlich für die
                    Behandlung der Umgebung, die Erstellung des richtigen include_path, und der
                    Übergabe von dem was auf der Kommandozeile angegeben wurde an die richtige
                    Bibliothekskomponente für die Bearbeitung.
                </para>

                <para>
                    Ultimativ, muss man zwei Dinge sicherstellen damit alles funktioniert,
                    unabhängig vom Betriebssystem auf dem man arbeitet:
                </para>

                <orderedlist>
                    <listitem>
                        <para>
                            <filename>zf.sh/zf.bat</filename> ist vom Systempfad aus erreichbar.
                            Das ist die Fähigkeit <command>zf</command> von überall aus aufzurufen,
                            unabhängig von aktuellen Arbeitsverzeichnisses.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <filename>ZendFramework/library</filename> ist im
                            <property>include_path</property>.
                        </para>
                    </listitem>
                </orderedlist>

                <note>
                    <para>
                        Zu beachten: Wärend das oben stehende sind die idealsten Notwendigkeiten
                        sind, kann man einfach Zend Framework herunterladen und erwarten das es
                        mit <filename>./path/to/zf.php</filename> und einem Kommando funktioniert.
                    </para>
                </note>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-starnix">
                <title>Das CLI Tool auf Unix-artigen Systemen einrichten</title>

                <para>
                    Das üblichste Setup in einer *nix Umgebung ist es, <filename>zf.sh</filename>
                    und <filename>zf.sh</filename> in das selbe Verzeichnis wie die
                    <acronym>PHP</acronym> Installation zu kopieren. Diese kann normalerweise in
                    einem der folgenden Plätze gefunden werden:
                </para>

                <programlisting language="text"><![CDATA[
/usr/bin
/usr/local/bin
/usr/local/ZendServer/bin/
/Applications/ZendServer/bin/
]]></programlisting>

                <para>
                    Um den Ort der eigenen <acronym>PHP</acronym> Installation zu finden kann man
                    'which php' auf der Kommandozeile ausführen. Das gibt den Ort der
                    <acronym>PHP</acronym> Installation zurück welche verwendet wird um in dieser
                    Umgebung <acronym>PHP</acronym> Skripte auszuführen.
                </para>

                <para>
                    Der nächste Schritt ist es sicherzustellen das die Zend Framework Bibliothek
                    korrekt im <acronym>PHP</acronym> <property>include_path</property> eingestellt
                    wurde. Um herauszufinden wo der <property>include_path</property> ist, kann man
                    <command>php -i</command> ausführen und nach der
                    <property>include_path</property> Variable sehen, oder kompakter
                    <command>php -i | grep include_path</command> ausführen. Sobald man
                    herausgefunden hat wo der <property>include_path</property> ist (er ist
                    normalerweise etwas wie <filename>/usr/lib/php</filename>,
                    <filename>/usr/share/php</filename>, <filename>/usr/local/lib/php</filename>,
                    oder so ähnlich), sollte man sicherstellen das der Inhalt des Verzeichnisses
                    <filename>/library/</filename> in einem der in <property>include_path</property>
                    spezifizierten Verzeichnisse ist.
                </para>

                <para>
                    Sobald man diese zwei Dinge getan hat, sollte man in der Lage sein ein Kommando
                    auszuführen und die richtige Antwort zurück zu erhalten, wie zum Beispiel:
                </para>

                <para>
                    <inlinegraphic scale="100" align="center" valign="middle"
                        fileref="figures/zend.tool.framework.cliversionunix.png" format="PNG" />
                </para>

                <para>
                    Wenn man diese Art der Ausgabe nicht sieht, sollte man zurückgeben und die
                    eigenen Einstellungen prüfen um sicherzustellen das man alle notwendigen Teile
                    am richtigen Ort vorhanden sind.
                </para>

                <para>
                    Es gibt eine Anzahl an alternativen Einstellungen die man erstellen kann,
                    abhängig von der Konfiguration des Servers, dem Zugriffslevel, oder aus anderen
                    Gründen.
                </para>

                <para>
                    Das <emphasis>alternative Setup</emphasis> enthält das man den Download vom Zend
                    Framework zusammenbehält wie er ist, und einen Link von einem
                    <constant>PATH</constant> Ort zur <filename>zf.sh</filename> erstellt. Was dies
                    bedeutet ist, dass man den Inhalt des Zend Framework Downloads in einem Ort wie
                    <filename>/usr/local/share/ZendFramework</filename> platzieren kann, oder
                    lokaler unter <filename>/home/username/lib/ZendFramework</filename> und einen
                    symbolischen Link zu <filename>zf.sh</filename> erstellt.
                </para>

                <para>
                    Angenommen man will den Link in <filename>/usr/local/bin</filename> platzieren
                    (dies könnte zum Beispiel auch für die Platzierung des Links unter
                    <filename>/home/username/bin/</filename> funktionieren), dan würde man ein
                    Kommando wie das folgende platzieren:
                </para>

                <programlisting language="sh"><![CDATA[
ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf

# ODER (zum Beispiel)
ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf
]]></programlisting>

                <para>
                    Das erstellt einen Link auf den man global von der Kommandozeile aus zugreifen
                    kann.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-windows">
                <title>Das CLI Tool unter Windows einrichten</title>

                <para>
                    Das üblichste Setup in einer Windows Win32 Umgebung ist es
                    <filename>zf.bat</filename> und <filename>zf.php</filename> in das selbe
                    Verzeichnis wie die <acronym>PHP</acronym> Bibliothek zu kopieren. Diese kann
                    generell an einem der folgenden Plätze gefunden werden:
                </para>

                <programlisting language="text"><![CDATA[
C:\PHP
C:\Program Files\ZendServer\bin\
C:\WAMP\PHP\bin
]]></programlisting>

                <para>
                    Man sollte in der Lage sein <filename>php.exe</filename> von der Kommandozeile
                    aus auszuführen. Wenn man dazu nicht in der Lage ist, sollte man zuerst die
                    Dokumentation prüfen welche mit der <acronym>PHP</acronym> Bibliothek
                    mitgeliefert wird, um sicherzustellen dass der Pfad zu
                    <filename>php.exe</filename> in der Windows Umgebungsvariable
                    <constant>PATH</constant> zu finden ist.
                </para>

                <para>
                    Der nächste Schritt besteht darin sicherzustellen das die Zend Framework
                    Bibliothek richtig auf dem <acronym>PHP</acronym>
                    <property>include_path</property> des Systems eingerichtet ist. Um
                    herauszufinden wo der <property>include_path</property> ist, kann man
                    <command>php -i</command> eingeben und nach der Variable
                    <property>include_path</property> sehen, oder kompakter
                    <command>php -i | grep include_path</command> ausführen wenn man ein Cygwin
                    Setup mit vorhandenem grep hat. Sobald man herausgefunden hat wo der
                    <property>include_path</property> liegt (das ist normalerweise etwas wie
                    <filename>C:\PHP\pear</filename>, <filename>C:\PHP\share</filename>,
                    <filename>C:\Program%20Files\ZendServer\share</filename>, oder ähnlich), sollte
                    man sicherstellen das der Inhalt des Verzeichnisses library/ in einem vom
                    <property>include_path</property> spezifizierten Verzeichnis ist.
                </para>

                <para>
                    Sobald man diese zwei Dinge getan hat, sollte man in der Lage sein ein Kommando
                    auszuführen und die richtige Antwort, so ähnlich wie die folgende, zu erhalten:
                </para>

                <para>
                    <inlinegraphic scale="100" align="center" valign="middle"
                        fileref="figures/zend.tool.framework.cliversionwin32.png" format="PNG" />
                </para>

                <para>
                    Wenn man diese Art der Ausgabe nicht sieht, sollte man zurückgehen und die
                    Einstellungen prüfen um sicherzustellen das man alle notwendigen Teile an den
                    richtigen Orten hat.
                </para>

                <para>
                    Es gibt eine Anzahl an alternativen Einstellungen die man erstellen kann,
                    abhängig von der Konfiguration des Servers, dem Zugriffslevel, oder aus anderen
                    Gründen.
                </para>

                <para>
                    Das <emphasis>alternative Setup</emphasis> enthält das man den Download vom Zend
                    Framework zusammenbehält wie er ist, und sowohl den System
                    <constant>PATH</constant>, als auch die <filename>php.ini</filename> Datei
                    verändert. In der Umgebung des Benutzers muss man
                    <filename>C:\Path\To\ZendFramework\bin</filename> hinzufügen damit die Datei
                    <filename>zf.bat</filename> ausführbar ist. Auch die Datei
                    <filename>php.ini</filename> ist zu verändern um sicherzustellen das
                    <filename>C:\Path\To\ZendFramework\library</filename> im
                    <property>include_path</property> liegt.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.cli-client.setup-othernotes">
                <title>Andere Einstellungs-Möglichkeiten</title>

                <para>
                    Wenn man aus bestimmten Gründen die Zend Framework Bibliothek nicht im
                    <property>include_path</property> haben will, gibt es andere Optionen. Es gibt
                    zwei spezielle Umgebungsvariablen welche <filename>zf.php</filename> verwendet
                    um den Ort der Zend Framework Installation zu erkennen.
                </para>

                <para>
                    Die erste ist <constant>ZEND_TOOL_INCLUDE_PATH_PREPEND</constant>, welche den
                    Wert der Umgebungsvariable dem <property>include_path</property> des Systems
                    (<filename>php.ini</filename>) voranstellt bevor der Client geladen wird.
                </para>

                <para>
                    Alternativ kann man <constant>ZEND_TOOL_INCLUDE_PATH</constant> verwenden um den
                    <property>include_path</property> des System komplett zu
                    <emphasis>ersetzen</emphasis> für jene bei denen es Sinn macht, speziell für das
                    <command>zf</command> Kommandozeilen-Tool.
                </para>
            </sect4>
        </sect3>

        <sect3 id="zend.tool.extending.zend-tool-framework.providers-and-manifests">
            <title>Erstellen von Providern</title>

            <para>
                Generell, ist ein Provider für sich selbst gesehen, nichts weiter als eine Shell für
                einen Entwickler um einige Möglichkeiten zu bündeln welche er mit den Kommandozeilen
                (oder anderen) Clients ausführen will. Das ist eine Analogie für das was der
                "Controller" in der <acronym>MVC</acronym> Anwendung ist.
            </para>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.loading">
                <title>Wie Zend Tool eigene Provider findet</title>

                <para>
                    Standardmäßig verwendet Zend Tool den BasicLoader um alle Provider zu finden die
                    es ausführen kann. Er durchsucht alle Verzeichnisse des Include Pfades rekursiv
                    und öffnet alle Dateien welche mit "Manifest.php" oder "Provider.php" enden.
                    Alle Klassen in diesen Dateien werden darauf durchsucht ob Sie entweder
                    <classname>Zend_Tool_Framework_Provider_Interface</classname> oder
                    <classname>Zend_Tool_Framework_Manifest_ProviderManifestable</classname>
                    implementieren. Instanzen des Provider Interfaces sind für die echte
                    Funktionalität zuständig und alle Ihre öffentlichen Methoden kann als Provider
                    Aktionen zugegriffen werden. Das ProviderManifestable Interface benötigt
                    trotzdem die Implementation einer <methodname>getProviders()</methodname>
                    Methode welche ein Array an instanzierten Provider Interface Instanzen
                    zurückgibt.
                </para>

                <para>
                    Die folgenden Namensregeln sind darauf anzuwenden, wie man auf die Provider
                    zugreifen kann welche vom IncludePathLoader gefunden werden:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            Der letzte Teil des eigenen Klassennamens welcher von einem Unterstrich
                            getrennt ist, wird für den Providernamen verwendet, zum Beispiel führt
                            "My_Provider_Hello" zum Provider auf welchen mit dem Namen "hello"
                            zugegriffen werden kann.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Wenn der Provider eine Methode <methodname>getName()</methodname> hat,
                            dann wird diese verwendet statt der vorherigen Methode um den Namen zu
                            erkennen.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Wenn der Provider den Präfix "Provider" hat, zum Beispiel wenn er
                            <classname>My_HelloProvider</classname> heißt, dann wird er vom Namen
                            entfernt so dass der Provider "hello" heißt.
                        </para>
                    </listitem>
                </itemizedlist>

                <note>
                    <para>
                        Der IncludePathLoader folgt Symlinks nicht, was bedeutet das man Provider
                        Funktionalitäten nicht in den Include Pfaden verlinken kann, sondern dass
                        Sie physikalisch in den Include Pfaden vorhanden sein müssen.
                    </para>
                </note>

                <example id="zend.tool.extending.zend-tool-framework.providers-and-manifests.loading.example">
                    <title>Provider mit einem Manifest bekanntmachen</title>

                    <para>
                        You can expose your providers to Zend Tool by offering a manifest
                        with a special filename ending with "Manifest.php".
                        A Provider Manifest is an implementation of the
                        <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
                        and requires the <methodname>getProviders()</methodname> method to return
                        an array of instantiated providers. In anticipation of our first
                        own provider <classname>My_Component_HelloProvider</classname>
                        we will create the following manifest:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_Manifest
    implements Zend_Tool_Framework_Manifest_ProviderManifestable
{
    public function getProviders()
    {
        return array(
            new My_Component_HelloProvider()
        );
    }
}
]]></programlisting>

                </example>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.basic">
                <title>Basic Instructions for Creating Providers</title>

                <para>
                    As an example, if a developer wants to add the capability of showing
                    the version of a datafile that his 3rd party component is working
                    from, there is only one class the developer would need to implement.
                    Assuming the component is called <classname>My_Component</classname>, he would
                    create a class named <classname>My_Component_HelloProvider</classname> in a
                    file named <filename>HelloProvider.php</filename> somewhere on the
                    <property>include_path</property>. This class would implement
                    <classname>Zend_Tool_Framework_Provider_Interface</classname>, and the body of
                    this file would only have to look like the following:
                </para>

                <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say()
    {
        echo 'Hello from my provider!';
    }
}
]]></programlisting>

                <para>
                    Given that code above, and assuming the developer wishes to access
                    this functionality through the console client, the call would look
                    like this:
                </para>

                <programlisting language="sh"><![CDATA[
% zf say hello
Hello from my provider!
]]></programlisting>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.response">
                <title>The response object</title>

                <para>
                    As discussed in the architecture section Zend Tool allows to hook different clients for
                    using your Zend Tool providers. To keep compliant with different clients you should
                    use the response object to return messages from your providers instead of using
                    <methodname>echo()</methodname> or a similiar output mechanism. Rewritting our hello
                    provider with this knowledge it looks like:
                </para>

                <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $this->_registry->getResponse
                        ->appendContent("Hello from my provider!");
    }
}
]]></programlisting>

                <para>
                    As you can see one has to extend the <classname>Zend_Tool_Framework_Provider_Abstract</classname>
                    to gain access to the Registry which holds the <classname>Zend_Tool_Framework_Client_Response</classname>
                    instance.
                </para>
            </sect4>

            <sect4 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced">
                <title>Advanced Development Information</title>

                <sect5 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.variables">
                    <title>Passing Variables to a Provider</title>

                    <para>
                        The above "Hello World" example is great for simple commands, but
                        what about something more advanced? As your scripting and tooling
                        needs grow, you might find that you need the ability to accept
                        variables. Much like function signatures have parameters, your
                        tooling requests can also accept parameters.
                    </para>

                    <para>
                        Just as each tooling request can be isolated to a method within a
                        class, the parameters of a tooling request can also be isolated in a
                        very well known place. Parameters of the action methods of a
                        provider can include the same parameters you want your client to
                        utilize when calling that provider and action combination. For
                        example, if you wanted to accept a name in the above example, you
                        would probably do this in OO code:
                    </para>

                <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = 'Ralph')
    {
        echo 'Hello' . $name . ', from my provider!';
    }
}
]]></programlisting>

                    <para>
                        The above example can then be called via the command line
                        <command>zf say hello Joe</command>. "Joe" will be supplied to the provider as
                        a parameter of the method call. Also note, as you see that the
                        parameter is optional, that means it is also optional on the command
                        line, so that <command>zf say hello</command> will still work, and default
                        to the name "Ralph".
                    </para>

                </sect5>

                <sect5 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.prompt">
                    <title>Prompt the User for Input</title>

                    <para>
                        There are cases when the workflow of your provider requires
                        to prompt the user for input. This can be done by requesting
                        the client to ask for more the required input by calling:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say($name = 'Ralph')
    {
        $nameResponse = $this->_registry
                             ->getClient()
                             ->promptInteractiveInput("Whats your name?");
        $name = $name->getContent();

        echo 'Hello' . $name . ', from my provider!';
    }
}
]]></programlisting>

                    <para>
                        This command throws an exception if the current client is not
                        able to handle interactive requests. In case of the default Console Client
                        however you will be asked to enter the name.
                    </para>
                </sect5>

                <sect5 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.pretendable">
                    <title>Pretending to execute a Provider Action</title>

                    <para>
                        Another interesting feature you might wish to implement is
                        <emphasis>pretendability</emphasis>. Pretendabilty is the ability
                        for your provider to "pretend" as if it is doing the requested
                        action and provider combination and give the user as much
                        information about what it <emphasis>would</emphasis> do without
                        actually doing it. This might be an important notion when doing
                        heavy database or filesystem modifications that the user might not
                        otherwise want to do.
                    </para>

                    <para>
                        Pretendability is easy to implement. There are two parts to this
                        feature: 1) marking the provider as having the ability to "pretend",
                        and 2) checking the request to ensure the current request was indeed
                        asked to be "pretended". This feature is demonstrated in the code
                        sample below.
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends    Zend_Tool_Framework_Provider_Abstract
    implements Zend_Tool_Framework_Provider_Pretendable
{
    public function say($name = 'Ralph')
    {
        if ($this->_registry->getRequest()->isPretend()) {
            echo 'I would say hello to ' . $name . '.';
        } else {
            echo 'Hello' . $name . ', from my provider!';
        }
    }
}
]]></programlisting>

                    <para>
                        To run the provider in pretend mode just call:
                    </para>

                    <programlisting language="sh"><![CDATA[
% zf --pretend say hello Ralph
I would say hello Ralph.
]]></programlisting>

                </sect5>

                <sect5 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.verbosedebug">
                    <title>Verbose and Debug modes</title>

                    <para>
                        You can also run your provider actions in "verbose" or "debug" modes.
                        The semantics in regard to this actions have to be implemented by you
                        in the context of your provider. You can access debug or verbose modes
                        with:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = 'Ralph')
    {
        if($this->_registry->getRequest()->isVerbose()) {
            echo "Hello::say has been called\n";
        }
        if($this->_registry->getRequest()->isDebug()) {
            syslog(LOG_INFO, "Hello::say has been called\n");
        }
    }
}
]]></programlisting>
                </sect5>

                <sect5 id="zend.tool.extending.zend-tool-framework.providers-and-manifests.advanced.configstorage">
                    <title>Accessing User Config and Storage</title>

                    <para>
                        Using the Enviroment variable <property>ZF_CONFIG_FILE</property> or the
                        .zf.ini in your home directory you can inject configuration parameters into
                        any Zend Tool provider. Access to this configuration is available via the
                        registry that is passed to your provider if you extend
                        <classname>Zend_Tool_Framework_Provider_Abstract</classname>.
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $username = $this->_registry->getConfig()->username;
        if(!empty($username)) {
            echo "Hello $username!";
        } else {
            echo "Hello!";
        }
    }
}
]]></programlisting>

                    <para>
                        The returned configuration is of the type
                        <classname>Zend_Tool_Framework_Client_Config</classname> but internally the
                        <methodname>__get()</methodname> and <methodname>__set()</methodname> magic methods
                        proxy to a <classname>Zend_Config</classname> of the given configuration type.
                    </para>

                    <para>
                        The storage allows to save arbitrary data for later reference. This can be useful for batch
                        processing tasks or for re-runs of your tasks. You can access the storage in a similar way
                        like the configuration:
                    </para>

                    <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $aValue = $this->_registry->getStorage()->get("myUsername");
        echo "Hello $aValue!";
    }
}
]]></programlisting>

                    <para>
                        The API of the storage is very simple:
                    </para>

                    <programlisting language="php"><![CDATA[
class Zend_Tool_Framework_Client_Storage
{
    public function setAdapter($adapter);
    public function isEnabled();
    public function put($name, $value);
    public function get($name, $defaultValue=null);
    public function has($name);
    public function remove($name);
    public function getStreamUri($name);
}
]]></programlisting>

                    <important>
                        <para>
                            When designing your providers that are config or storage aware remember to
                            check if the required user-config or storage keys really exist for a user.
                            You won't run into fatal errors when none of these are provided though,
                            since empty ones are created upon request.
                        </para>
                    </important>
                </sect5>

            </sect4>

        </sect3>

    </sect2>

    <sect2 id="zend.tool.extending.zend-tool-project">
        <title>Zend_Tool_Project Extensions</title>

        <para>
            Zend_Tool_Project exposes a rich set of functionality and capabilities that make the task
            of creating new providers, specficially those targetting project easier and more manageable.
        </para>

        <sect3 id="zend.tool.extending.zend-tool-project.architecture">
            <title>Overall Architecture</title>

            <para>
                This same concept applies to Zend Framework projects. In Zend Framework projects, you have
                controllers, actions, views, models, databases and so on and so forth. In terms of
                <classname>Zend_Tool</classname>, we need a way to track these types of resources - thus
                <classname>Zend_Tool_Project</classname>.
            </para>

            <para>
                <classname>Zend_Tool_Project</classname> is capable of tracking project resources throughout
                the development of a project. So, for example, if in one command you created a controller,
                and in the next command you wish to create an action within that controller,
                <classname>Zend_Tool_Project</classname> is gonna have to <emphasis>know</emphasis> about
                the controller file you created so that you can (in the next action), be able to append that
                action to it. This is what keeps our projects up to date and <emphasis>stateful</emphasis>.
            </para>

            <para>
                Another important point to understand about projects is that typically, resources are
                organized in a hierarchical fashion. With that in mind,
                <classname>Zend_Tool_Project</classname> is capable of serializing the current project into
                a internal representation that allows it to keep track of not only <emphasis>what</emphasis>
                resources are part of a project at any given time, but also <emphasis>where</emphasis> they
                are in relation to one another.
            </para>

        </sect3>


        <sect3 id="zend.tool.extending.zend-tool-project.providers">
            <title>Creating Providers</title>

            <para>
                Project specific providers are created in the same fashion as plain framework providers, with
                one exception: project providers must extend the <code>Zend_Tool_Project_Provider_Abstract</code>.
                This class comes with some significant functionality that helps developers load existing project,
                obtian the profile object, and be able to search the profile, then later store any changes to the
                current project profile.
            </para>

            <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    extends Zend_Tool_Project_Provider_Abstract
{
    public function say()
    {
        $profile = $this->_loadExistingProfile();

        /* ... do project stuff here */

        $this->_storeProfile();
    }
}
]]></programlisting>

        </sect3>

        <!--
        <sect3 id="zend.tool.extending.zend-tool-project.resources-and-contexts">
            <title>Creating Resources &amp; Contexts</title>



        </sect3>
        -->

    </sect2>
</sect1>