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:

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.

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.

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.

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:

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

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!

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.