|
|
@@ -1,8 +1,398 @@
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
-<!-- EN-Revision: 15103 -->
|
|
|
+<!-- EN-Revision: 19568 -->
|
|
|
<!-- Reviewed: no -->
|
|
|
<sect1 id="zend.tool.framework.writing-providers">
|
|
|
<title>Creando Proveedores para usar con Zend_Tool_Framework</title>
|
|
|
- <para/>
|
|
|
- <!-- @todo -->
|
|
|
+ <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 <acronym>MVC</acronym> application.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <sect2 id="zend.tool.framework.writing-providers.loading">
|
|
|
+ <title>How Zend Tool finds your Providers</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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
|
|
|
+ <classname>Zend_Tool_Framework_Provider_Interface</classname>
|
|
|
+ or <classname>Zend_Tool_Framework_Manifest_ProviderManifestable</classname>.
|
|
|
+ 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
|
|
|
+ <methodname>getProviders()</methodname> which returns an array of
|
|
|
+ instantiated provider interface instances.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The following naming rules apply on how you can access the providers
|
|
|
+ that were found by the IncludePathLoader:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ 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".
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ If your provider has a method <methodname>getName()</methodname>
|
|
|
+ it will be used instead of the previous method to determine
|
|
|
+ the name.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ If your provider has "Provider" as prefix, e.g. it is called
|
|
|
+ <classname>My_HelloProvider</classname> it will be stripped
|
|
|
+ from the name so that the provider will be called "hello".
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>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.</para>
|
|
|
+ </note>
|
|
|
+
|
|
|
+ <example id="zend.tool.framework.writing-providers.loading.example">
|
|
|
+ <title>Exposing Your Providers with a Manifest</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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
|
|
|
+ <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
|
|
|
+ and requires the <methodname>getProviders()</methodname> method to return
|
|
|
+ an array of instantiated providers. In anticipation of our first
|
|
|
+ own provider <classname>My_Component_HelloProvider</classname>
|
|
|
+ we will create the following manifest:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+class My_Component_Manifest
|
|
|
+ implements Zend_Tool_Framework_Manifest_ProviderManifestable
|
|
|
+{
|
|
|
+ public function getProviders()
|
|
|
+ {
|
|
|
+ return array(
|
|
|
+ new My_Component_HelloProvider()
|
|
|
+ );
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ </example>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <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 <classname>My_Component</classname>, he would
|
|
|
+ create a class named <classname>My_Component_HelloProvider</classname> in a
|
|
|
+ file named <filename>HelloProvider.php</filename> somewhere on the
|
|
|
+ <property>include_path</property>. 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.response">
|
|
|
+ <title>The response object</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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
|
|
|
+ <methodname>echo()</methodname> or a similiar output mechanism. Rewritting our hello
|
|
|
+ provider with this knowledge it looks like:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+class My_Component_HelloProvider
|
|
|
+ extends Zend_Tool_Framework_Provider_Abstract
|
|
|
+{
|
|
|
+ public function say()
|
|
|
+ {
|
|
|
+ $this->_registry->getResponse
|
|
|
+ ->appendContent("Hello from my provider!");
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ As you can see one has to extend the <classname>Zend_Tool_Framework_Provider_Abstract</classname>
|
|
|
+ to gain access to the Registry which holds the <classname>Zend_Tool_Framework_Client_Response</classname>
|
|
|
+ instance.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="zend.tool.framework.writing-providers.advanced">
|
|
|
+ <title>Advanced Development Information</title>
|
|
|
+
|
|
|
+ <sect3 id="zend.tool.framework.writing-providers.advanced.variables">
|
|
|
+ <title>Passing Variables to a Provider</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
|
|
|
+ <command>zf say hello Joe</command>. "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 <command>zf say hello</command> will still work, and default
|
|
|
+ to the name "Ralph".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="zend.tool.framework.writing-providers.advanced.prompt">
|
|
|
+ <title>Prompt the User for Input</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+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!';
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="zend.tool.framework.writing-providers.advanced.pretendable">
|
|
|
+ <title>Pretending to execute a Provider Action</title>
|
|
|
+
|
|
|
+ <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>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ To run the provider in pretend mode just call:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="sh"><![CDATA[
|
|
|
+% zf --pretend say hello Ralph
|
|
|
+I would say hello Ralph.
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="zend.tool.framework.writing-providers.advanced.verbosedebug">
|
|
|
+ <title>Verbose and Debug modes</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+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");
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="zend.tool.framework.writing-providers.advanced.configstorage">
|
|
|
+ <title>Accessing User Config and Storage</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Using the Enviroment variable <property>ZF_CONFIG_FILE</property> 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
|
|
|
+ <classname>Zend_Tool_Framework_Provider_Abstract</classname>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+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!";
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The returned configuration is of the type
|
|
|
+ <classname>Zend_Tool_Framework_Client_Config</classname> but internally the
|
|
|
+ <methodname>__get()</methodname> and <methodname>__set()</methodname> magic methods
|
|
|
+ proxy to a <classname>Zend_Config</classname> of the given configuration type.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 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:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+class My_Component_HelloProvider
|
|
|
+ extends Zend_Tool_Framework_Provider_Abstract
|
|
|
+{
|
|
|
+ public function say()
|
|
|
+ {
|
|
|
+ $aValue = $this->_registry->getStorage()->get("myUsername");
|
|
|
+ echo "Hello $aValue!";
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The API of the storage is very simple:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+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);
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <important>
|
|
|
+ <para>
|
|
|
+ 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.
|
|
|
+ </para>
|
|
|
+ </important>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ </sect2>
|
|
|
</sect1>
|
benjamin-gonzales