Zend_Tool_Framework 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 PHP Klassen in den PHP include_path 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, XML-RPC, SOAP, und andere. Zend_Tool_Project baut auf die Möglichkeiten von Zend_Tool_Framework 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. Zend_Tool_Framework bietet das folgende: Gemeinsame Interfaces und Abstraktes welche es Entwicklern erlauben Funktionalitäten und Möglichkeiten zu erstellen welche durch Tooling Clients verwendbar sind. Grundsätzliche Client Funktionalität und eine konkrete Konsolenimplementation welche externe Tools und Interfaces mit Zend_Tool_Framework verbindet. Der Konsolenclient kann in CLI Umgebungen verwendet werden, wie Unix Shells und der Windows Konsole. "Provider" und "Manifest" Interfaces 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. Ein introspektives Ladesystem welches die Umgebung auf Provider scannt und erkennt was benötigt wird um Sie auszuführen. Ein Standardset von System Provider 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". Definitionen welche man in diesem Handbuch in Bezug auf Zend_Tool_Framework beachten sollte sind: Zend_Tool_Framework - Der Framework welche die Tooling Möglichkeiten bereitstellt. Tooling Client - Ein Entwickler-Tool welches sich zum Zend_Tool_Framework verbindet und Ihn verwendet. Client - Das Subsystem von Zend_Tool_Framework welches ein Interface bereitstellt so das sich Tooling-Clienten verbinden, und Kommandos abfragen und ausführen können. Konsolen Client / Kommandozeilen Interface / zf.php - Der Tooling Client für die Kommandozeile. Provider - Ein Subsystem und eine Sammlung von eingebauten Funktionalitäten welche der Framework exportiert. Manifest - Ein Subsystem für die Definition, Organisation, und Verbreitung von Daten welche Provider benötigen. Zend_Tool_Project Provider - Ein Set von Providern speziell für die Erstellung und die Wartung von Zend Framework basierenden Projekten. Das CLI, oder Kommandozeilen-Tool (intern als das Konsolen-Tool bekannt) ist aktuell das primäre Interface für die Bearbeitung von Zend_Tool Anfragen. Mit dem CLI 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 cmd.exe, Console2 und mit dem Cygwin Projekt. 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 .sh oder .bat welche mit der Zend Framework Distribution bereitgestellt wird. Im Trunk kann er hier gefunden werden: http://framework.zend.com/svn/framework/standard/trunk/bin/. Wie man sehen kann, gibt es 3 Dateien im /bin/ Verzeichnis: zf.php, zf.sh, und zf.bat. zf.sh und zf.bat sind Betriebssystem-spezifische Client-Wrapper: zf.sh für die *nix Umgebung, und zf.bat für die Win32 Umgebung. Diese Client-Wrapper sind für das Finden der richtigen php.exe, das finden der zf.php, und die Übergabe an die Anfrage des Clients zuständig. Die zf.php 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. Ultimativ, muss man zwei Dinge sicherstellen damit alles funktioniert, unabhängig vom Betriebssystem auf dem man arbeitet: zf.sh/zf.bat ist vom Systempfad aus erreichbar. Das ist die Fähigkeit zf von überall aus aufzurufen, unabhängig von aktuellen Arbeitsverzeichnisses. ZendFramework/library ist im include_path. Zu beachten: Wärend das oben stehende sind die idealsten Notwendigkeiten sind, kann man einfach Zend Framework herunterladen und erwarten das es mit ./path/to/zf.php und einem Kommando funktioniert. Das üblichste Setup in einer *nix Umgebung ist es, zf.sh und zf.sh in das selbe Verzeichnis wie die PHP Installation zu kopieren. Diese kann normalerweise in einem der folgenden Plätze gefunden werden: Um den Ort der eigenen PHP Installation zu finden kann man 'which php' auf der Kommandozeile ausführen. Das gibt den Ort der PHP Installation zurück welche verwendet wird um in dieser Umgebung PHP Skripte auszuführen. Der nächste Schritt ist es sicherzustellen das die Zend Framework Bibliothek korrekt im PHP include_path eingestellt wurde. Um herauszufinden wo der include_path ist, kann man php -i ausführen und nach der include_path Variable sehen, oder kompakter php -i | grep include_path ausführen. Sobald man herausgefunden hat wo der include_path ist (er ist normalerweise etwas wie /usr/lib/php, /usr/share/php, /usr/local/lib/php, oder so ähnlich), sollte man sicherstellen das der Inhalt des Verzeichnisses /library/ in einem der in include_path spezifizierten Verzeichnisse ist. 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: 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. 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. Das alternative Setup enthält das man den Download vom Zend Framework zusammenbehält wie er ist, und einen Link von einem PATH Ort zur zf.sh erstellt. Was dies bedeutet ist, dass man den Inhalt des Zend Framework Downloads in einem Ort wie /usr/local/share/ZendFramework platzieren kann, oder lokaler unter /home/username/lib/ZendFramework und einen symbolischen Link zu zf.sh erstellt. Angenommen man will den Link in /usr/local/bin platzieren (dies könnte zum Beispiel auch für die Platzierung des Links unter /home/username/bin/ funktionieren), dan würde man ein Kommando wie das folgende platzieren: Das erstellt einen Link auf den man global von der Kommandozeile aus zugreifen kann. Das üblichste Setup in einer Windows Win32 Umgebung ist es zf.bat und zf.php in das selbe Verzeichnis wie die PHP Bibliothek zu kopieren. Diese kann generell an einem der folgenden Plätze gefunden werden: Man sollte in der Lage sein php.exe von der Kommandozeile aus auszuführen. Wenn man dazu nicht in der Lage ist, sollte man zuerst die Dokumentation prüfen welche mit der PHP Bibliothek mitgeliefert wird, um sicherzustellen dass der Pfad zu php.exe in der Windows Umgebungsvariable PATH zu finden ist. Der nächste Schritt besteht darin sicherzustellen das die Zend Framework Bibliothek richtig auf dem PHP include_path des Systems eingerichtet ist. Um herauszufinden wo der include_path ist, kann man php -i eingeben und nach der Variable include_path sehen, oder kompakter php -i | grep include_path ausführen wenn man ein Cygwin Setup mit vorhandenem grep hat. Sobald man herausgefunden hat wo der include_path liegt (das ist normalerweise etwas wie C:\PHP\pear, C:\PHP\share, C:\Program%20Files\ZendServer\share, oder ähnlich), sollte man sicherstellen das der Inhalt des Verzeichnisses library/ in einem vom include_path spezifizierten Verzeichnis ist. 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: 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. 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. Das alternative Setup enthält das man den Download vom Zend Framework zusammenbehält wie er ist, und sowohl den System PATH, als auch die php.ini Datei verändert. In der Umgebung des Benutzers muss man C:\Path\To\ZendFramework\bin hinzufügen damit die Datei zf.bat ausführbar ist. Auch die Datei php.ini ist zu verändern um sicherzustellen das C:\Path\To\ZendFramework\library im include_path liegt. Wenn man aus bestimmten Gründen die Zend Framework Bibliothek nicht im include_path haben will, gibt es andere Optionen. Es gibt zwei spezielle Umgebungsvariablen welche zf.php verwendet um den Ort der Zend Framework Installation zu erkennen. Die erste ist ZEND_TOOL_INCLUDE_PATH_PREPEND, welche den Wert der Umgebungsvariable dem include_path des Systems (php.ini) voranstellt bevor der Client geladen wird. Alternativ kann man ZEND_TOOL_INCLUDE_PATH verwenden um den include_path des System komplett zu ersetzen für jene bei denen es Sinn macht, speziell für das zf Kommandozeilen-Tool. 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 MVC Anwendung ist. 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 Zend_Tool_Framework_Provider_Interface oder Zend_Tool_Framework_Manifest_ProviderManifestable 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 getProviders() Methode welche ein Array an instanzierten Provider Interface Instanzen zurückgibt. Die folgenden Namensregeln sind darauf anzuwenden, wie man auf die Provider zugreifen kann welche vom IncludePathLoader gefunden werden: 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. Wenn der Provider eine Methode getName() hat, dann wird diese verwendet statt der vorherigen Methode um den Namen zu erkennen. Wenn der Provider den Präfix "Provider" hat, zum Beispiel wenn er My_HelloProvider heißt, dann wird er vom Namen entfernt so dass der Provider "hello" heißt. 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. 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 Zend_Tool_Framework_Manifest_ProviderManifestable and requires the getProviders() method to return an array of instantiated providers. In anticipation of our first own provider My_Component_HelloProvider we will create the following manifest: 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 My_Component, he would create a class named My_Component_HelloProvider in a file named HelloProvider.php somewhere on the include_path. This class would implement Zend_Tool_Framework_Provider_Interface, and the body of this file would only have to look like the following: Given that code above, and assuming the developer wishes to access this functionality through the console client, the call would look like this: 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 echo() or a similiar output mechanism. Rewritting our hello provider with this knowledge it looks like: _registry->getResponse ->appendContent("Hello from my provider!"); } } ]]> As you can see one has to extend the Zend_Tool_Framework_Provider_Abstract to gain access to the Registry which holds the Zend_Tool_Framework_Client_Response instance. 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. 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: The above example can then be called via the command line zf say hello Joe. "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 zf say hello will still work, and default to the name "Ralph". 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: _registry ->getClient() ->promptInteractiveInput("Whats your name?"); $name = $name->getContent(); echo 'Hello' . $name . ', from my provider!'; } } ]]> 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. Another interesting feature you might wish to implement is pretendability. 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 would 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. 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. _registry->getRequest()->isPretend()) { echo 'I would say hello to ' . $name . '.'; } else { echo 'Hello' . $name . ', from my provider!'; } } } ]]> To run the provider in pretend mode just call: 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: _registry->getRequest()->isVerbose()) { echo "Hello::say has been called\n"; } if($this->_registry->getRequest()->isDebug()) { syslog(LOG_INFO, "Hello::say has been called\n"); } } } ]]> Using the Enviroment variable ZF_CONFIG_FILE 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 Zend_Tool_Framework_Provider_Abstract. _registry->getConfig()->username; if(!empty($username)) { echo "Hello $username!"; } else { echo "Hello!"; } } } ]]> The returned configuration is of the type Zend_Tool_Framework_Client_Config but internally the __get() and __set() magic methods proxy to a Zend_Config of the given configuration type. 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: _registry->getStorage()->get("myUsername"); echo "Hello $aValue!"; } } ]]> The API of the storage is very simple: 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. 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. 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 Zend_Tool, we need a way to track these types of resources - thus Zend_Tool_Project. Zend_Tool_Project 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, Zend_Tool_Project is gonna have to know 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 stateful. Another important point to understand about projects is that typically, resources are organized in a hierarchical fashion. With that in mind, Zend_Tool_Project is capable of serializing the current project into a internal representation that allows it to keep track of not only what resources are part of a project at any given time, but also where they are in relation to one another. Project specific providers are created in the same fashion as plain framework providers, with one exception: project providers must extend the Zend_Tool_Project_Provider_Abstract. 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. _loadExistingProfile(); /* ... do project stuff here */ $this->_storeProfile(); } } ]]>