Previous topic

Next topic

Creating Providers to use with Zend_Tool_Framework

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 IncludePathLoader 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:

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:

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

{

publicfunction 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:

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:

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.

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:

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.

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:

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.