<ac:macro ac:name="unmigrated-wiki-markup"><ac:plain-text-body><![CDATA[h1. Current Architecture / Wil's Proposal
Zend_Build defines a build system as a system by which the act of "doing something" is defined by actions, such as create or delete, and resources, such as project, file, directory and so on. This deviates from the format of current build systems in that they define the act of doing something in terms of projects, targets and tasks. Zend_Build is currently environment agnostic. What this means is that Zend_Build is to be harnessed by a consuming system in such a way to translate user requests into an "actionable resource".
Zend_Build also includes methods by which Resources and Actions can export their requirements. This system is called the Zend_Build_Manifest system. The primary means of transporting metadata (such as required parameters, resource and action names) to an external system, would be via XML in a structure defined by Zend_Build_Manifest. The ideas that this metadata live in a Manifest xml file are supported by the notions that external tools (or harnesses described above), can use this metadata to boostrap their system, as well as know what Zend_Build's Action and Resources require in order to complete their respective tasks. Zend_Build_Manifest includes techniques by which these Manifest files can be scanned for an found on a system for automatic loading (as long as they are in the include_path.)
The general philosophy behind these two namespaces is to be able to abstract out common "actions" and common "resources" into self contained object classes.
Actions exist to abstract out the "verb" of the action/resource pair. Common actions would include "create", "delete" or "remove", and "list" to name a few. The general idea behind this level of abstraction is that regardless of the resource being acted upon, the actual "action" would not anything different in the way of parameters, on screen help, or the verbosity of said action. Presumably, all actions, (lets take "Create" as an example) would share the same basic characteristics regardless of the resources the action is preformed upon. So with our example, "create" would across the board require parameters such as how much verbosity to output, be able to provide generalized help, and so on. For all intents and purposes, Actions serve as a consistency layer for naming actions with regards to resources.
Resources would contain the bulk of the code required to do any one job. The structure of a resource is such that after implementing the necessary abstract interface, the resource must also implement a method per supported action. As an example, a resource called "File" would need to implement a create method for the work of the "create" action. This is the same for any other supported action like "delete", "view" and so on.
Both actions and resources share similar concepts within their implementation. Both would support the setting and retrieval of parameters. Both would require concrete implementations to implement both a validate() and an execute() method. These methods are there to ensure that a request to the system is both provided all the parameters as well as a well formed environment. The validate() method should ensure that all parameters that are necessary for proper execution are available before calling the execute() method. The execute() method on resources will proxy to the method within the resource of the same name as the action being acted on said resource.
The general philosophy behind Zend_Build_Manfiest is to provide a system by which components can register their requirements into a global manifest. The registration of requirements and general awareness allows the consuming system (for example a command line tool) to provide a better interface to users through knowing what's available within the given code-base.
Technically speaking, Zend_Build_Manifest operates in such a manner that placement of files matching a specified pattern, and their contents in a specified format, these manifest files can be loaded and parsed into the Zend_Build_Manifest registry. Once these requirements are registered, the consuming system can provide better UI as well as giving the user a better understanding of what is required to execute a specific action/resource pair.
Manifest files (currently) should match the file pattern Name-ZFManifest.xml. The contents of the file should match the following format:
For all intents and purposes, xml shall be the metadata format. The general reasoning behind this choice as the intermediate metadata format is so that external tools that have xml capabilities can also read these files and be able to provide UI for a consuming system (in this case perhaps Zend Studio) that might want to provide support for executing these action/resources.
The Zend_Tool namespace represents the Command Line Tools classes of the Zend Framework
The Zend_Tool_Cli* classes represent the consuming subsystem that ultimately provides the CLI interface / UI that user will interact with to use the Zend_Build system.
To effectively do its job of parsing the above, Zend_Tool_Cli uses a incremental argument parser to break down a command line request into action / resource pairs.
The decision of using an incremental parser allows Zend_Tool_Cli to short circuit argument parsing at any point without regard for any future (later in the command string) parts. For example, if a user supplies a command line of "zf create --help", the parser would normally expect a 3rd parameter in the form of the name of a resource name (as in "create what?"). In this case, the incremental parser can now stop after the action "create" and its option "--help", since the option passed to the create action generally indicates the end of a command line request.
This includes the classes Zend_Tool_Cli_Context_Global, Zend_Tool_Cli_Context_Action, and Zend_Tool_Cli_Context_Resource.
The classes in this group make up the incremental argument parsers for the Zend_Tool_Cli system. As a command line string is passed in, it is broken into parts and passed down the line of parsers, each removing parts relative to its own context and then passing the remaining arguments down the line.
As an example, lets take the command "zf -v create project -d ./here/". When this is passed into the system, there are 5 distinct parts: "-v", "create", "project", "-d", and "./here". When Zend_Tool_Cli_Context is given this array of args, the first processor that runs is Zend_Tool_Cli_Context_Global. When this parser is run, it will extract any parts that are relative to the "Global Context". In the case of this example, the "-v" is taken off the stack, and the remaining parts are passed down the line. The next parser to run is the Zend_Tool_Cli_Context_Action parser. It sees "create", which is formatted in such a way to represent an action name. Thusly, "create" is taken off the parts array, and the remainder are passed onto the next contextual parser. Lastly, the Zend_Tool_Cli_Context_Resource runs and parses out the parts "project", as well as the "-d" and "./here" as they represent a set of options pertinent to the "project" resource.
This method for decomposing a string command allows for the maximum amount of flexibility for extending and injecting custom actions and/or resources into the Zend_Build system via a Command Line Tool.
zf/zf.php/zf.bat is the main() function expected to exist in a file on the users PATH, presumably named zf.php. This file will accept the $_ARGS and present them to the Zend_Tool_Cli object for translating the CLI environment specific stuff into Zend_Build sane objects for completing the request.
This will be talked about at a later date as to not get the goals and objectives confused with the system laid out above.