Extending Zend_Tool

Overview of Zend_Tool

Zend_Tool_Framework is a framework for exposing common functionalities such as the creation of project scaffolds, code generation, search index generation, and much more. Functionality may be written and exposed via PHP classes dropped into the PHP include_path, providing incredible flexibility of implementation. The functionality may then be consumed by writing implementation and/or protocol-specific clients -- such as console clients, XML-RPC, SOAP, and much more.

Zend_Tool_Project builds on and extends the capabilities of Zend_Tool_Framework to that of managing a "project". In general, a "project" is a planned endeavor or an initiative. In the computer world, projects generally are a collection of resources. These resources can be files, directories, databases, schemas, images, styles, and more.

Zend_Tool_Framework Extensions

Overall Architecture

Zend_Tool_Framework provides the following:

Common interfaces and abstracts that allow developers to create functionality and capabilities that are dispatchable by tooling clients.
Base client functionality and a concrete console implementation that connect external tools and interfaces to the Zend_Tool_Framework. The Console client may be used in CLI environments such as unix shells and the Windows console.
"Provider" and "Manifest" interfaces that can be utilized by the tooling system. "Providers" represent the functional aspect of the framework, and define the actions that tooling clients may call. "Manifests" act as metadata registries that provide additional context for the various defined providers.
An introspective loading system that will scan the environment for providers and determine what is required to dispatch them.
A standard set of system providers that allow the system to report what the full capabilities of the system are as well as provide useful feedback. This also includes a comprehensive "Help System".

Definitions that you should be aware of through this manual with respect to Zend_Tool_Framework include:

Zend_Tool_Framework - The framework which exposes tooling capabilities.
Tooling Client - A developer tool that connects to and consumes Zend_Tool_Framework.
Client - The subsystem of Zend_Tool_Framework that exposes an interface such that tooling clients can connect, query and execute commands.
Console Client / Command Line Interface / zf.php - The tooling client for the command line.
Provider - A subsystem and a collection of built-in functionality that the framework exports.
Manifest - A subsystem for defining, organizing, and disseminating provider requirement data.
Zend_Tool_Project Provider - A set of providers specifically for creating and maintaining Zend Framework-based projects.

Understanding the CLI Client

The CLI, or command line tool (internally known as the console tool), is currently the primary interface for dispatching Zend_Tool requests. With the CLI tool, developers can issue tooling requests inside the "command line windows", also commonly known as a "terminal" window. This environment is predominant in the *nix environment, but also has a common implementation in windows with the cmd.exe, console2 and also with the Cygwin project.

Setting up the CLI tool

To issue tooling requests via the command line client, you first need to set up the client so that your system can handle the "zf" command. The command line client, for all intents and purposes, is the .sh or .bat file that is provided with your Zend Framework distribution. In trunk, it can be found here: » http://framework.zend.com/svn/framework/standard/trunk/bin/.

As you can see, there are 3 files in the /bin/ directory: a zf.php, zf.sh, and zf.bat. The zf.sh and the zf.bat are the operating system specific client wrappers: zf.sh for the *nix environment, and zf.bat for the Win32 environment. These client wrappers are responsible for finding the proper php.exe, finding the zf.php, and passing on the client request. The zf.php is the responsible for handling understanding your environment, constructing the proper include_path, and passing what is provided on the command line to the proper library component for dispatching.

Ultimately, you want to ensure two things to make everything work regardless of the operating system you are on:

zf.sh/zf.bat is reachable from your system path. This is the ability to call zf from anywhere on your command line, regardless of what your current working directory is.
ZendFramework/library is in your include_path.

Note: Note: while the above are the most ideal requirements, you can simply download Zend Framework and expect it to work as ./path/to/zf.php some command.

Setting up the CLI tool on Unix-like Systems

The most common setup in the *nix environment, is to copy the zf.sh and zf.php into the same directory as your PHP binary. This can generally be found in one of the following places:

/usr/bin
/usr/local/bin
/usr/local/ZendServer/bin/
/Applications/ZendServer/bin/

To find out the location of your PHP binary, you can execute 'which php' on the command line. This will return the location of the PHP binary you will be using to run PHP scripts in this environment.

The next order of business is to ensure that Zend Framework library is set up correctly inside of the system PHP include_path. To find out where your include_path is located, you can execute php -i and look for the include_path variable, or more succinctly, execute php -i | grep include_path. Once you have found where your include_path is located (this will generally be something like /usr/lib/php, /usr/share/php, /usr/local/lib/php, or similar), ensure that the contents of the /library/ directory are put inside your include_path specified directory.

Once you have done those two things, you should be able to issue a command and get back the proper response like this:

If you do not see this type of output, go back and check your setup to ensure you have all of the necessary pieces in the proper place.

There are a couple of alternative setups you might want to employ depending on your servers configuration, your level of access, or for other reasons.

Alternative Setup involves keeping the Zend Framework download together as is, and creating a link from a PATH location to the zf.sh. What this means is you can place the contents of the ZendFramework download into a location such as /usr/local/share/ZendFramework, or more locally like /home/username/lib/ZendFramework, and creating a symbolic link to the zf.sh.

Assuming you want to put the link inside /usr/local/bin (this could also work for placing the link inside /home/username/bin/ for example) you would issue a command similar to this:

ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf
 
# OR (for example)
ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf

This will create a link which you should be able to access globally on the command line.

Setting up the CLI tool on Windows

The most common setup in the Windows Win32 environment, is to copy the zf.bat and zf.php into the same directory as your PHP binary. This can generally be found in one of the following places:

C:\PHP
C:\Program Files\ZendServer\bin\
C:\WAMP\PHP\bin

You should be able to run php.exe on the command line. If you are not able to, first check the documentation that came with your PHP distribution, or ensure that the path to php.exe is in your Windows PATH environment variable.

The next order of business is to ensure that Zend Framework library is set up correctly inside of the system PHP include_path. To find out where your include_path is located, you can type php -i and look for the include_path variable, or more succinctly execute php -i | grep include_path if you have Cygwin setup with grep available. Once you have found where your include_path is located (this will generally be something like C:\PHP\pear, C:\PHP\share, C:\Program%20Files\ZendServer\share or similar), ensure that the contents of the library/ directory are put inside your include_path specified directory.

Once you have done those two things, you should be able to issue a command and get back the proper response like this:

If you do not see this type of output, go back and check your setup to ensure you have all of the necessary pieces in the proper place.

There are a couple of alternative setups you might want to employ depending on your server's configuration, your level of access, or for other reasons.

Alternative Setup involves keeping the Zend Framework download together as is, and altering both your system PATH as well as the php.ini file. In your user's environment, make sure to add C:\Path\To\ZendFramework\bin, so that your zf.bat file is executable. Also, alter the php.ini file to ensure that C:\Path\To\ZendFramework\library is in your include_path.

Other Setup Considerations

If for some reason you do not want Zend Framework library inside your include_path, there is another option. There are two special environment variables that zf.php will utilize to determine the location of your Zend Framework installation.

The first is ZEND_TOOL_INCLUDE_PATH_PREPEND, which will prepend the value of this environment variable to the system (php.ini) include_path before loading the client.

Alternatively, you might want to use ZEND_TOOL_INCLUDE_PATH to completely replace the system include_path for one that makes sense specifically for the zf command line tool.

Creating Providers

In general, a provider, on its own, is nothing more than the shell for a developer to bundle up some capabilities they wish to dispatch with the command line (or other) clients. It is an analogue to what a "controller" is inside of your MVC application.

How Zend_Tool finds your Providers

By default Zend_Tool uses the BasicLoader to find all the providers that you can run. It recursivly iterates all include path directories and opens all files that end with "Manifest.php" or "Provider.php". All classes in these files are inspected if they implement either Zend_Tool_Framework_Provider_Interface or Zend_Tool_Framework_Manifest_ProviderManifestable. Instances of the provider interface make up for the real functionality and all their public methods are accessible as provider actions. The ProviderManifestable interface however requires the implementation of a method getProviders() which returns an array of instantiated provider interface instances.

The following naming rules apply on how you can access the providers that were found by the IncludePathLoader:

The last part of your classname split by underscore is used for the provider name, e.g. "My_Provider_Hello" leads to your provider being accessible by the name "hello".
If your provider has a method getName() it will be used instead of the previous method to determine the name.
If your provider has "Provider" as prefix, e.g. it is called My_HelloProvider it will be stripped from the name so that the provider will be called "hello".

Note: The IncludePathLoader does not follow symlinks, that means you cannot link provider functionality into your include paths, they have to be physically present in the include paths.

Example #1 Exposing Your Providers with a Manifest

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:

class My_Component_Manifest
    implements Zend_Tool_Framework_Manifest_ProviderManifestable
{
    public function getProviders()
    {
        return array(
            new My_Component_HelloProvider()
        );
    }
}

Basic Instructions for Creating Providers

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:

class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say()
    {
        echo 'Hello from my provider!';
    }
}

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

% zf say hello
Hello from my provider!

The response object

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:

class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $this->_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.

Advanced Development Information

Passing Variables to a Provider

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:

class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = 'Ralph')
    {
        echo 'Hello' . $name . ', from my provider!';
    }
}

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".

Prompt the User for Input

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:

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!';
    }
}

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.

Pretending to execute a Provider Action

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.

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!';
        }
    }
}

To run the provider in pretend mode just call:

% zf --pretend say hello Ralph
I would say hello Ralph.

Verbose and Debug modes

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:

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");
        }
    }
}

Accessing User Config and Storage

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.

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!";
        }
    }
}

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:

class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $aValue = $this->_registry->getStorage()->get("myUsername");
        echo "Hello $aValue!";
    }
}

The API of the storage is very simple:

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);
}

Important

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 Extensions

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.

Overall Architecture

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.

Creating Providers

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.

class My_Component_HelloProvider
    extends Zend_Tool_Project_Provider_Abstract
{
    public function say()
    {
        $profile = $this->_loadExistingProfile();
 
        /* ... do project stuff here */
 
        $this->_storeProfile();
    }
}