repo_zf1Php7/documentation/manual/en/module_specs/Zend_Tool_Framework-WritingProviders.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.tool.framework.writing-providers">
    <title>Creating Providers to use with Zend_Tool_Framework</title>

    <para>
        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.
    </para>

    <sect2 id="zend.tool.framework.writing-providers.basic">
        <title>Basic Instructions for Creating Providers</title>

        <para>
            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 <code>My_Component</code>, he would
            create a class named <code>My_Component_HelloProvider</code> in a
            file named <code>HelloProvider.php</code> somewhere on the
            <code>include_path</code>. This class would implement
            <classname>Zend_Tool_Framework_Provider_Interface</classname>, and the body of
            this file would only have to look like the following:
        </para>

        <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say()
    {
        echo 'Hello from my provider!';
    }
}
]]></programlisting>

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

        <programlisting language="sh"><![CDATA[
% zf say hello
Hello from my provider!
]]></programlisting>
    </sect2>

    <sect2 id="zend.tool.framework.writing-providers.advanced">
        <title>Advanced Development Information</title>

        <para>
            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.
        </para>

        <para>
            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:
        </para>

        <programlisting language="php"><![CDATA[
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = 'Ralph')
    {
        echo 'Hello' . $name . ', from my provider!';
    }
}
]]></programlisting>

        <para>
            The above example can then be called via the command line <code>zf
                say hello Joe</code>. "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 <code>zf say hello</code> will still work, and default
            to the name "Ralph".
        </para>

        <para>
            Another interesting feature you might wish to implement is
            <emphasis>pretendability</emphasis>. 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 <emphasis>would</emphasis> 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.
        </para>

        <para>
            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.
        </para>

        <programlisting language="php"><![CDATA[
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!';
        }
    }
}
]]></programlisting>
    </sect2>
</sect1>