1 <?xml version="1.0" encoding="UTF-8"?>
3 <!-- EN-Revision: 21741 -->
4 <sect1 id="zend.tool.framework.writing-providers">
5 <title>Zend_Tool_Frameworkを利用してプロバイダを作成する</title>
9 コマンドラインでクライアント(またはそれ以外)をディスパッチすることを求めるいくらかの能力をバンドルするための、
10 開発者のためのシェル以外の何物でもありません。
11 <acronym>MVC</acronym>アプリケーションの中での「コントローラ」と似ています。
14 <sect2 id="zend.tool.framework.writing-providers.loading">
15 <title>Zend_Tool はどのようにプロバイダを見つけるか</title>
18 By default <classname>Zend_Tool</classname> uses the IncludePathLoader to find all
19 the providers that you can run. It recursivly iterates all
20 include path directories and opens all files that end
21 with "Manifest.php" or "Provider.php". All classes in these
22 files are inspected if they implement either
23 <classname>Zend_Tool_Framework_Provider_Interface</classname>
24 or <classname>Zend_Tool_Framework_Manifest_ProviderManifestable</classname>.
25 Instances of the provider interface make up for the real functionality
26 and all their public methods are accessible as provider actions.
27 The ProviderManifestable interface however requires the implementation of a method
28 <methodname>getProviders()</methodname> which returns an array of
29 instantiated provider interface instances.
33 The following naming rules apply on how you can access the providers
34 that were found by the IncludePathLoader:
40 The last part of your classname split by underscore is used
41 for the provider name, e.g. "My_Provider_Hello" leads to your
42 provider being accessible by the name "hello".
48 If your provider has a method <methodname>getName()</methodname>
49 it will be used instead of the previous method to determine
56 If your provider has "Provider" as prefix, e.g. it is called
57 <classname>My_HelloProvider</classname> it will be stripped
58 from the name so that the provider will be called "hello".
65 The IncludePathLoader does not follow symlinks, that means
66 you cannot link provider functionality into your include paths,
67 they have to be physically present in the include paths.
71 <example id="zend.tool.framework.writing-providers.loading.example">
72 <title>Exposing Your Providers with a Manifest</title>
75 You can expose your providers to <classname>Zend_Tool</classname> by offering a manifest
76 with a special filename ending with "Manifest.php".
77 A Provider Manifest is an implementation of the
78 <interface>Zend_Tool_Framework_Manifest_ProviderManifestable</interface>
79 and requires the <methodname>getProviders()</methodname> method to return
80 an array of instantiated providers. In anticipation of our first
81 own provider <classname>My_Component_HelloProvider</classname>
82 we will create the following manifest:
85 <programlisting language="php"><![CDATA[
86 class My_Component_Manifest
87 implements Zend_Tool_Framework_Manifest_ProviderManifestable
89 public function getProviders()
92 new My_Component_HelloProvider()
101 <sect2 id="zend.tool.framework.writing-providers.basic">
102 <title>プロバイダを作成するための基本命令</title>
105 例えば、サード・パーティのコンポーネントが働かせる
106 データファイルのバージョンを示す能力を開発者が加えたければ、
107 開発者が実装する必要があるクラスが1つだけあります。
108 もしコンポーネントが<classname>My_Component</classname>と呼ばれるなら、
109 <property>include_path</property>上のどこかに<filename>HelloProvider.php</filename>という名前のファイルで
110 <classname>My_Component_HelloProvider</classname>という名のクラスを作成するでしょう。
111 このクラスは<classname>Zend_Tool_Framework_Provider_Interface</classname>を実装します、
112 そして、このファイルの本体は以下のように見えなければならないだけです:
115 <programlisting language="php"><![CDATA[
116 class My_Component_HelloProvider
117 implements Zend_Tool_Framework_Provider_Interface
119 public function say()
121 echo 'Hello from my provider!';
128 コンソール・クライアントを通じて開発者がこの機能にアクセスしたけれ、
132 <programlisting language="sh"><![CDATA[
134 Hello from my provider!
138 <sect2 id="zend.tool.framework.writing-providers.response">
139 <title>レスポンスオブジェクト</title>
142 As discussed in the architecture section <classname>Zend_Tool</classname> allows to hook different clients for
143 using your <classname>Zend_Tool</classname> providers. To keep compliant with different clients you should
144 use the response object to return messages from your providers instead of using
145 <methodname>echo()</methodname> or a similiar output mechanism. Rewritting our hello
146 provider with this knowledge it looks like:
149 <programlisting language="php"><![CDATA[
150 class My_Component_HelloProvider
151 extends Zend_Tool_Framework_Provider_Abstract
153 public function say()
155 $this->_registry->getResponse
156 ->appendContent("Hello from my provider!");
162 As you can see one has to extend the <classname>Zend_Tool_Framework_Provider_Abstract</classname>
163 to gain access to the Registry which holds the <classname>Zend_Tool_Framework_Client_Response</classname>
168 <sect2 id="zend.tool.framework.writing-providers.advanced">
169 <title>先進の開発情報</title>
171 <sect3 id="zend.tool.framework.writing-providers.advanced.variables">
172 <title>プロバイダに変数を渡す</title>
175 上記の例の "Hello World" は、単純なコマンドとして有名です、
176 しかし、より進んだ何かについてはどうでしょうか?
177 スクリプトを書くこととツーリングの必要性が高まるにつれ、
178 変数を扱う能力を必要とすると気付くかもしれません。
179 だいたいのファンクション・シグニチャにはパラメータがあるように、
180 ツーリング・リクエストはパラメータを受け入れることもできます。
184 各々のツーリング・リクエストがクラス内でメソッドに分離されることができると、
185 ツーリング・リクエストのパラメータはきわめて周知の立場で分離されることもできます。
186 プロバイダのアクション・メソッドのパラメータは、
187 クライアントがそのプロバイダとアクションの組合せを呼ぶとき、
188 利用することを望む同じパラメータを含むことができます。
189 たとえば、あなたが上記の例で名前を扱いたいならば、
190 あなたは多分オブジェクト指向コードでこうするでしょう:
193 <programlisting language="php"><![CDATA[
194 class My_Component_HelloProvider
195 implements Zend_Tool_Framework_Provider_Interface
197 public function say($name = 'Ralph')
199 echo 'Hello' . $name . ', from my provider!';
205 それから上記の例は、コマンドライン<command>zf say hello Joe</command>によって呼ぶことができます。
206 "Joe" は、メソッド呼び出しのパラメータとして、プロバイダに供給されます。
208 パラメータが任意だとあなたがわかるように、
209 <command>zf say hello</command>がさらに機能して、名前 "Ralph" にデフォルト設定するように、
210 コマンドライン上で選択できることを意味します。
215 <sect3 id="zend.tool.framework.writing-providers.advanced.prompt">
216 <title>Prompt the User for Input</title>
219 There are cases when the workflow of your provider requires
220 to prompt the user for input. This can be done by requesting
221 the client to ask for more the required input by calling:
224 <programlisting language="php"><![CDATA[
225 class My_Component_HelloProvider
226 extends Zend_Tool_Framework_Provider_Abstract
228 public function say($name = 'Ralph')
230 $nameResponse = $this->_registry
232 ->promptInteractiveInput("Whats your name?");
233 $name = $name->getContent();
235 echo 'Hello' . $name . ', from my provider!';
241 This command throws an exception if the current client is not
242 able to handle interactive requests. In case of the default Console Client
243 however you will be asked to enter the name.
247 <sect3 id="zend.tool.framework.writing-providers.advanced.pretendable">
248 <title>プロバイダ・アクションを実行するための擬態</title>
251 あなたが実装したいかもしれないもう一つの面白い特徴は、<emphasis>擬態性</emphasis>です。
253 まるでそれがリクエストされたアクションとプロバイダの組み合わせを実行しているように擬態して、
254 実際にそれを実行せずに、それが実行するで<emphasis>あろう</emphasis>ことについて沢山の情報をユーザーに与えることを
256 これ以外の場合にはユーザーが実行したくないかもしれない重いデータベースや、
257 ファイルシステム修正をするときに重要な小道具であるかもしれません。
262 このフィーチャーには2つの要素があります:
263 1) プロバイダが「擬態する」能力を持つことを示します。
265 「擬態する」よう要求されたことを確実にするために、リクエストをチェックします。
266 このフィーチャーは下記のコードサンプルで示されます。
269 <programlisting language="php"><![CDATA[
270 class My_Component_HelloProvider
271 extends Zend_Tool_Framework_Provider_Abstract
272 implements Zend_Tool_Framework_Provider_Pretendable
274 public function say($name = 'Ralph')
276 if ($this->_registry->getRequest()->isPretend()) {
277 echo 'I would say hello to ' . $name . '.';
279 echo 'Hello' . $name . ', from my provider!';
286 擬態モードでプロバイダを実行してちょっと呼び出し
289 <programlisting language="sh"><![CDATA[
290 % zf --pretend say hello Ralph
291 I would say hello Ralph.
296 <sect3 id="zend.tool.framework.writing-providers.advanced.verbosedebug">
297 <title>冗長及びデバッグモード</title>
300 You can also run your provider actions in "verbose" or "debug" modes.
301 The semantics in regard to this actions have to be implemented by you
302 in the context of your provider. You can access debug or verbose modes
306 <programlisting language="php"><![CDATA[
307 class My_Component_HelloProvider
308 implements Zend_Tool_Framework_Provider_Interface
310 public function say($name = 'Ralph')
312 if($this->_registry->getRequest()->isVerbose()) {
313 echo "Hello::say has been called\n";
315 if($this->_registry->getRequest()->isDebug()) {
316 syslog(LOG_INFO, "Hello::say has been called\n");
323 <sect3 id="zend.tool.framework.writing-providers.advanced.configstorage">
324 <title>ユーザーの構成及びストレージにアクセス</title>
327 Using the Enviroment variable <property>ZF_CONFIG_FILE</property> or the
328 .zf.ini in your home directory you can inject configuration parameters into
329 any <classname>Zend_Tool</classname> provider. Access to this configuration is available via the
330 registry that is passed to your provider if you extend
331 <classname>Zend_Tool_Framework_Provider_Abstract</classname>.
334 <programlisting language="php"><![CDATA[
335 class My_Component_HelloProvider
336 extends Zend_Tool_Framework_Provider_Abstract
338 public function say()
340 $username = $this->_registry->getConfig()->username;
341 if(!empty($username)) {
342 echo "Hello $username!";
351 The returned configuration is of the type
352 <classname>Zend_Tool_Framework_Client_Config</classname> but internally the
353 <methodname>__get</methodname> and <methodname>__set</methodname> magic methods
354 proxy to a <classname>Zend_Config</classname> of the given configuration type.
358 The storage allows to save arbitrary data for later reference. This can be useful for batch
359 processing tasks or for re-runs of your tasks. You can access the storage in a similar way
360 like the configuration:
363 <programlisting language="php"><![CDATA[
364 class My_Component_HelloProvider
365 extends Zend_Tool_Framework_Provider_Abstract
367 public function say()
369 $aValue = $this->_registry->getStorage()->get("myUsername");
370 echo "Hello $aValue!";
379 <programlisting language="php"><![CDATA[
380 class Zend_Tool_Framework_Client_Storage
382 public function setAdapter($adapter);
383 public function isEnabled();
384 public function put($name, $value);
385 public function get($name, $defaultValue=null);
386 public function has($name);
387 public function remove($name);
388 public function getStreamUri($name);
394 When designing your providers that are config or storage aware remember to
395 check if the required user-config or storage keys really exist for a user.
396 You won't run into fatal errors when none of these are provided though,
397 since empty ones are created upon request.