PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

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:

<?php
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:

<?php
class My_Component_HelloProvider
    
extends Zend_Tool_Framework_Provider_Abstract
{
    public function 
say($name 'Ralph')
    {
        
$nameResponse $this->_registry
                             
->getClient()
                             ->
promptInteractiveInput("Whats your name?");
        
$name $nameResponse->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.

<?php
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:

<?php
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.

<?php
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:

<?php
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:

<?php
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 Framework