1 <?xml version="1.0" encoding="UTF-8"?>
3 <sect1 id="zend.tool.framework.writing-providers">
4 <title>Creating Providers to use with Zend_Tool_Framework</title>
7 In general, a provider, on its own, is nothing more than the shell for a
8 developer to bundle up some capabilities they wish to dispatch with the
9 command line (or other) clients. It is an analogue to what a
10 "controller" is inside of your <acronym>MVC</acronym> application.
13 <sect2 id="zend.tool.framework.writing-providers.loading">
14 <title>How Zend_Tool finds your Providers</title>
17 By default <classname>Zend_Tool</classname> uses the IncludePathLoader to find all
18 the providers that you can run. It recursivly iterates all
19 include path directories and opens all files that end
20 with "Manifest.php" or "Provider.php". All classes in these
21 files are inspected if they implement either
22 <classname>Zend_Tool_Framework_Provider_Interface</classname>
23 or <classname>Zend_Tool_Framework_Manifest_ProviderManifestable</classname>.
24 Instances of the provider interface make up for the real functionality
25 and all their public methods are accessible as provider actions.
26 The ProviderManifestable interface however requires the implementation of a method
27 <methodname>getProviders()</methodname> which returns an array of
28 instantiated provider interface instances.
32 The following naming rules apply on how you can access the providers
33 that were found by the IncludePathLoader:
39 The last part of your classname split by underscore is used
40 for the provider name, e.g. "My_Provider_Hello" leads to your
41 provider being accessible by the name "hello".
47 If your provider has a method <methodname>getName()</methodname>
48 it will be used instead of the previous method to determine
55 If your provider has "Provider" as prefix, e.g. it is called
56 <classname>My_HelloProvider</classname> it will be stripped
57 from the name so that the provider will be called "hello".
64 The IncludePathLoader does not follow symlinks, that means
65 you cannot link provider functionality into your include paths,
66 they have to be physically present in the include paths.
70 <example id="zend.tool.framework.writing-providers.loading.example">
71 <title>Exposing Your Providers with a Manifest</title>
74 You can expose your providers to <classname>Zend_Tool</classname> by offering a
75 manifest with a special filename ending with "Manifest.php".
76 A Provider Manifest is an implementation of the
77 <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
78 and requires the <methodname>getProviders()</methodname> method to return
79 an array of instantiated providers. In anticipation of our first
80 own provider <classname>My_Component_HelloProvider</classname>
81 we will create the following manifest:
84 <programlisting language="php"><![CDATA[
85 class My_Component_Manifest
86 implements Zend_Tool_Framework_Manifest_ProviderManifestable
88 public function getProviders()
91 new My_Component_HelloProvider()
99 <sect2 id="zend.tool.framework.writing-providers.basic">
100 <title>Basic Instructions for Creating Providers</title>
103 As an example, if a developer wants to add the capability of showing
104 the version of a datafile that his 3rd party component is working
105 from, there is only one class the developer would need to implement.
106 Assuming the component is called <classname>My_Component</classname>, he would
107 create a class named <classname>My_Component_HelloProvider</classname> in a
108 file named <filename>HelloProvider.php</filename> somewhere on the
109 <property>include_path</property>. This class would implement
110 <classname>Zend_Tool_Framework_Provider_Interface</classname>, and the body of
111 this file would only have to look like the following:
114 <programlisting language="php"><![CDATA[
115 class My_Component_HelloProvider
116 implements Zend_Tool_Framework_Provider_Interface
118 public function say()
120 echo 'Hello from my provider!';
126 Given that code above, and assuming the developer wishes to access
127 this functionality through the console client, the call would look
131 <programlisting language="sh"><![CDATA[
133 Hello from my provider!
137 <sect2 id="zend.tool.framework.writing-providers.response">
138 <title>The response object</title>
141 As discussed in the architecture section <classname>Zend_Tool</classname> allows to hook
142 different clients for using your <classname>Zend_Tool</classname> providers. To keep
143 compliant with different clients you should use the response object to return messages
144 from your providers instead of using <methodname>echo()</methodname> or a similiar
145 output mechanism. Rewritting our hello provider with this knowledge it looks like:
148 <programlisting language="php"><![CDATA[
149 class My_Component_HelloProvider
150 extends Zend_Tool_Framework_Provider_Abstract
152 public function say()
154 $this->_registry->getResponse
155 ->appendContent("Hello from my provider!");
161 As you can see one has to extend the
162 <classname>Zend_Tool_Framework_Provider_Abstract</classname> to gain access to the
163 Registry which holds the <classname>Zend_Tool_Framework_Client_Response</classname>
168 <sect2 id="zend.tool.framework.writing-providers.advanced">
169 <title>Advanced Development Information</title>
171 <sect3 id="zend.tool.framework.writing-providers.advanced.variables">
172 <title>Passing Variables to a Provider</title>
175 The above "Hello World" example is great for simple commands, but
176 what about something more advanced? As your scripting and tooling
177 needs grow, you might find that you need the ability to accept
178 variables. Much like function signatures have parameters, your
179 tooling requests can also accept parameters.
183 Just as each tooling request can be isolated to a method within a
184 class, the parameters of a tooling request can also be isolated in a
185 very well known place. Parameters of the action methods of a
186 provider can include the same parameters you want your client to
187 utilize when calling that provider and action combination. For
188 example, if you wanted to accept a name in the above example, you
189 would probably do this in OO code:
192 <programlisting language="php"><![CDATA[
193 class My_Component_HelloProvider
194 implements Zend_Tool_Framework_Provider_Interface
196 public function say($name = 'Ralph')
198 echo 'Hello' . $name . ', from my provider!';
204 The above example can then be called via the command line
205 <command>zf say hello Joe</command>. "Joe" will be supplied to the provider as
206 a parameter of the method call. Also note, as you see that the
207 parameter is optional, that means it is also optional on the command
208 line, so that <command>zf say hello</command> will still work, and default
213 <sect3 id="zend.tool.framework.writing-providers.advanced.prompt">
214 <title>Prompt the User for Input</title>
217 There are cases when the workflow of your provider requires
218 to prompt the user for input. This can be done by requesting
219 the client to ask for more the required input by calling:
222 <programlisting language="php"><![CDATA[
223 class My_Component_HelloProvider
224 extends Zend_Tool_Framework_Provider_Abstract
226 public function say($name = 'Ralph')
228 $nameResponse = $this->_registry
230 ->promptInteractiveInput("Whats your name?");
231 $name = $nameResponse->getContent();
233 echo 'Hello' . $name . ', from my provider!';
239 This command throws an exception if the current client is not
240 able to handle interactive requests. In case of the default Console Client
241 however you will be asked to enter the name.
245 <sect3 id="zend.tool.framework.writing-providers.advanced.pretendable">
246 <title>Pretending to execute a Provider Action</title>
249 Another interesting feature you might wish to implement is
250 <emphasis>pretendability</emphasis>. Pretendabilty is the ability
251 for your provider to "pretend" as if it is doing the requested
252 action and provider combination and give the user as much
253 information about what it <emphasis>would</emphasis> do without
254 actually doing it. This might be an important notion when doing
255 heavy database or filesystem modifications that the user might not
256 otherwise want to do.
260 Pretendability is easy to implement. There are two parts to this
261 feature: 1) marking the provider as having the ability to "pretend",
262 and 2) checking the request to ensure the current request was indeed
263 asked to be "pretended". This feature is demonstrated in the code
267 <programlisting language="php"><![CDATA[
268 class My_Component_HelloProvider
269 extends Zend_Tool_Framework_Provider_Abstract
270 implements Zend_Tool_Framework_Provider_Pretendable
272 public function say($name = 'Ralph')
274 if ($this->_registry->getRequest()->isPretend()) {
275 echo 'I would say hello to ' . $name . '.';
277 echo 'Hello' . $name . ', from my provider!';
284 To run the provider in pretend mode just call:
287 <programlisting language="sh"><![CDATA[
288 % zf --pretend say hello Ralph
289 I would say hello Ralph.
293 <sect3 id="zend.tool.framework.writing-providers.advanced.verbosedebug">
294 <title>Verbose and Debug modes</title>
297 You can also run your provider actions in "verbose" or "debug" modes.
298 The semantics in regard to this actions have to be implemented by you
299 in the context of your provider. You can access debug or verbose modes
303 <programlisting language="php"><![CDATA[
304 class My_Component_HelloProvider
305 implements Zend_Tool_Framework_Provider_Interface
307 public function say($name = 'Ralph')
309 if($this->_registry->getRequest()->isVerbose()) {
310 echo "Hello::say has been called\n";
312 if($this->_registry->getRequest()->isDebug()) {
313 syslog(LOG_INFO, "Hello::say has been called\n");
320 <sect3 id="zend.tool.framework.writing-providers.advanced.configstorage">
321 <title>Accessing User Config and Storage</title>
324 Using the Enviroment variable <property>ZF_CONFIG_FILE</property> or the
325 .zf.ini in your home directory you can inject configuration parameters into
326 any <classname>Zend_Tool</classname> provider. Access to this configuration is
327 available via the registry that is passed to your provider if you extend
328 <classname>Zend_Tool_Framework_Provider_Abstract</classname>.
331 <programlisting language="php"><![CDATA[
332 class My_Component_HelloProvider
333 extends Zend_Tool_Framework_Provider_Abstract
335 public function say()
337 $username = $this->_registry->getConfig()->username;
338 if(!empty($username)) {
339 echo "Hello $username!";
348 The returned configuration is of the type
349 <classname>Zend_Tool_Framework_Client_Config</classname> but internally the
350 <methodname>__get()</methodname> and <methodname>__set()</methodname> magic methods
351 proxy to a <classname>Zend_Config</classname> of the given configuration type.
355 The storage allows to save arbitrary data for later reference. This can be useful
356 for batch processing tasks or for re-runs of your tasks. You can access the storage
357 in a similar way like the configuration:
360 <programlisting language="php"><![CDATA[
361 class My_Component_HelloProvider
362 extends Zend_Tool_Framework_Provider_Abstract
364 public function say()
366 $aValue = $this->_registry->getStorage()->get("myUsername");
367 echo "Hello $aValue!";
373 The <acronym>API</acronym> of the storage is very simple:
376 <programlisting language="php"><![CDATA[
377 class Zend_Tool_Framework_Client_Storage
379 public function setAdapter($adapter);
380 public function isEnabled();
381 public function put($name, $value);
382 public function get($name, $defaultValue=null);
383 public function has($name);
384 public function remove($name);
385 public function getStreamUri($name);
391 When designing your providers that are config or storage aware remember to
392 check if the required user-config or storage keys really exist for a user.
393 You won't run into fatal errors when none of these are provided though,
394 since empty ones are created upon request.