documentation/manual/ja/module_specs/Zend_Registry.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20819 -->
   4 <sect1 id="zend.registry.using">
   5
   6     <title>レジストリの使用法</title>
   7
   8     <para>
   9         レジストリは、アプリケーション空間でオブジェクトや変数を保存するためのコンテナです。
  10         変数をレジストリに保存すると、
  11         そのオブジェクトはアプリケーション内でいつでも利用できるようになります。
  12         この仕組みは、グローバルなストレージを使用する代わりに使用できます。
  13     </para>
  14
  15     <para>
  16         レジストリの典型的な使用法は、Zend_Registry
  17         クラスの静的メソッドを用いるものです。
  18         一方、このクラスは配列オブジェクトでもあるので、
  19         配列風のインターフェイスでアクセスすることもできます。
  20     </para>
  21
  22     <sect2 id="zend.registry.using.storing">
  23
  24         <title>レジストリへの値の設定</title>
  25
  26         <para>
  27             あるエントリをレジストリに保存するには、静的メソッド
  28             <methodname>set()</methodname> を使用します。
  29         </para>
  30
  31         <example id="zend.registry.using.storing.example">
  32             <title>set() メソッドの使用例</title>
  33             <programlisting language="php"><![CDATA[
  34 Zend_Registry::set('index', $value);
  35 ]]></programlisting>
  36         </example>
  37
  38         <para>
  39             値としては、オブジェクトや配列、スカラーを指定できます。
  40             レジストリの特定のエントリに保存されている値を変更するには、
  41             <methodname>set()</methodname> を使用して新しい値を指定します。
  42         </para>
  43
  44         <para>
  45             インデックスにはスカラー値 (<constant>NULL</constant>、文字列あるいは整数) を指定します。
  46             通常の配列と同じです。
  47         </para>
  48
  49     </sect2>
  50
  51     <sect2 id="zend.registry.using.retrieving">
  52
  53         <title>レジストリからの値の取得</title>
  54
  55         <para>
  56             エントリの内容をレジストリから取得するには、静的メソッド
  57             <methodname>get()</methodname> を使用します。
  58         </para>
  59
  60         <example id="zend.registry.using.retrieving.example">
  61             <title>get() メソッドの使用例</title>
  62             <programlisting language="php"><![CDATA[
  63 $value = Zend_Registry::get('index');
  64 ]]></programlisting>
  65         </example>
  66
  67         <para>
  68             <methodname>getInstance()</methodname> メソッドは、
  69             シングルトンレジストリオブジェクトを返します。
  70             このレジストリオブジェクトは順次処理をすることが可能 (iterable) で、
  71             レジストリ内の値に簡単にアクセスできます。
  72         </para>
  73
  74         <example id="zend.registry.using.retrieving.example-iterating">
  75             <title>レジストリの順次処理の例</title>
  76             <programlisting language="php"><![CDATA[
  77 $registry = Zend_Registry::getInstance();
  78
  79 foreach ($registry as $index => $value) {
  80     echo "レジストリのインデックス $index に含まれる内容:\n";
  81     var_dump($value);
  82 }
  83 ]]></programlisting>
  84         </example>
  85
  86     </sect2>
  87
  88     <sect2 id="zend.registry.using.constructing">
  89
  90         <title>レジストリオブジェクトの作成</title>
  91
  92         <para>
  93             静的メソッドを使用して静的なレジストリにアクセスするだけでなく、
  94             直接インスタンスを作成し、それをオブジェクトとして使用することもできます。
  95         </para>
  96
  97         <para>
  98             静的メソッドでアクセスするレジストリインスタンスは、
  99             単なるインスタンスのひとつであり、静的に格納されています。
 100             そのため、アプリケーション内のどこからでもアクセスできます。
 101         </para>
 102
 103         <para>
 104             <classname>Zend_Registry</classname> のインスタンスを作成するには、
 105             ごく普通に <code>new</code> コンストラクタを使用します。
 106             コンストラクタで <classname>Zend_Registry</classname>
 107             のインスタンスを作成する際に連想配列を渡すと、
 108             レジストリのエントリを初期化できるようになります。
 109         </para>
 110
 111         <example id="zend.registry.using.constructing.example">
 112             <title>レジストリを作成する例</title>
 113             <programlisting language="php"><![CDATA[
 114 $registry = new Zend_Registry(array('index' => $value));
 115 ]]></programlisting>
 116         </example>
 117
 118         <para>
 119             <classname>Zend_Registry</classname> のインスタンスを作成すると、
 120             配列風の方法でアクセスできるようになります。
 121             あるいは、静的メソッド <methodname>setInstance()</methodname>
 122             を使用することで、このインスタンスを <classname>Zend_Registry</classname>
 123             のシングルトンインスタンスに設定することもできます。
 124         </para>
 125
 126         <example id="zend.registry.using.constructing.example-setinstance">
 127             <title>シングルトンレジストリの初期化の例</title>
 128             <programlisting language="php"><![CDATA[
 129 $registry = new Zend_Registry(array('index' => $value));
 130
 131 Zend_Registry::setInstance($registry);
 132 ]]></programlisting>
 133         </example>
 134
 135         <para>
 136             <methodname>setInstance()</methodname> メソッドは、もしすでに
 137             静的レジストリが初期化されている場合に
 138             <classname>Zend_Exception</classname> をスローします。
 139         </para>
 140
 141     </sect2>
 142
 143     <sect2 id="zend.registry.using.array-access">
 144
 145         <title>レジストリへの配列風のアクセス</title>
 146
 147         <para>
 148             複数の値を取得したり設定したりする場合は、
 149             配列風の記法でアクセスすると便利でしょう。
 150         </para>
 151
 152         <example id="zend.registry.using.array-access.example">
 153             <title>配列アクセスの例</title>
 154             <programlisting language="php"><![CDATA[
 155 $registry = Zend_Registry::getInstance();
 156
 157 $registry['index'] = $value;
 158
 159 var_dump( $registry['index'] );
 160 ]]></programlisting>
 161         </example>
 162
 163     </sect2>
 164
 165     <sect2 id="zend.registry.using.array-object">
 166
 167         <title>オブジェクト形式でのレジストリへのアクセス</title>
 168
 169         <para>
 170             オブジェクト指向の方式で、
 171             インデックス名をオブジェクトのプロパティとしてアクセスできると便利でしょう。
 172             そうするには、オプション <constant>ArrayObject::ARRAY_AS_PROPS</constant>
 173             を指定してレジストリオブジェクトを明示的に作成し、
 174             静的インスタンスを初期化しなければなりません。
 175             <note>
 176                 <para><constant>ArrayObject::ARRAY_AS_PROPS</constant> オプションの設定は、
 177                 静的レジストリへの最初のアクセスの<emphasis>前に</emphasis>
 178                 行う必要があります。</para>
 179             </note>
 180         </para>
 181             <warning>
 182                 <title>ArrayObject::ARRAY_AS_PROPS オプションの既知の問題</title>
 183
 184                 <para>
 185                     <acronym>PHP</acronym> のバージョンによっては、
 186                     <constant>ArrayObject::ARRAY_AS_PROPS</constant>
 187                     オプションを指定してレジストリを使用するとバグが発生することがあります。
 188                 </para>
 189             </warning>
 190
 191         <example id="zend.registry.using.array-object.example">
 192             <title>オブジェクト形式のアクセスの例</title>
 193             <programlisting language="php"><![CDATA[
 194 // アプリケーションの起動ファイルでの記述
 195 $registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS)
 196 Zend_Registry::setInstance($registry);
 197 $registry->tree = 'apple';
 198
 199 .
 200 .
 201 .
 202
 203 // アプリケーション内の別の関数で、
 204 $registry = Zend_Registry::getInstance();
 205
 206 echo $registry->tree; // "apple" と出力します
 207
 208 $registry->index = $value;
 209
 210 var_dump($registry->index);
 211 ]]></programlisting>
 212         </example>
 213
 214     </sect2>
 215
 216     <sect2 id="zend.registry.using.isset">
 217
 218         <title>インデックスが存在するかどうかの確認</title>
 219
 220         <para>
 221             レジストリの特定のインデックスが値を持っているかどうかを調べるには、
 222             静的メソッド <methodname>isRegistered()</methodname> を使用します。
 223         </para>
 224
 225         <example id="zend.registry.using.isset.example-isregistered">
 226             <title>isRegistered() メソッドの使用例</title>
 227             <programlisting language="php"><![CDATA[
 228 if (Zend_Registry::isRegistered($index)) {
 229     $value = Zend_Registry::get($index);
 230 }
 231 ]]></programlisting>
 232         </example>
 233
 234         <para>
 235             レジストリの特定のインデックスが値を持っているかどうかを配列風に調べるには、
 236             通常の配列と同様に <methodname>isset()</methodname> を使用します。
 237         </para>
 238
 239         <example id="zend.registry.using.isset.example-isset">
 240             <title>isset() メソッドの使用例</title>
 241             <programlisting language="php"><![CDATA[
 242 $registry = Zend_Registry::getInstance();
 243
 244 // 配列風の構文でのアクセス
 245 if (isset($registry['index'])) {
 246     var_dump( $registry['index'] );
 247 }
 248
 249 // 有効にしていれば、オブジェクト形式でのアクセスも可能です
 250 if (isset($registry->index)) {
 251     var_dump( $registry->index );
 252 }
 253 ]]></programlisting>
 254         </example>
 255
 256     </sect2>
 257
 258     <sect2 id="zend.registry.using.subclassing">
 259
 260         <title>レジストリの拡張</title>
 261
 262         <para>
 263             静的レジストリは <classname>Zend_Registry</classname> クラスのインスタンスです。
 264             レジストリに何らかの機能を追加したい場合は、
 265             <classname>Zend_Registry</classname> を継承したクラスを作成し、
 266             それを静的レジストリで使用するシングルトンとして指定します。
 267             クラスを指定するには、静的メソッド
 268             <methodname>setClassName()</methodname> を使用します。
 269             <note>
 270                 <para>このクラスは <classname>Zend_Registry</classname> のサブクラスでなければなりません。</para>
 271             </note>
 272         </para>
 273
 274         <example id="zend.registry.using.subclassing.example">
 275             <title>シングルトンレジストリのクラス名を指定する例</title>
 276             <programlisting language="php"><![CDATA[
 277 Zend_Registry::setClassName('My_Registry');
 278
 279 Zend_Registry::set('index', $value);
 280 ]]></programlisting>
 281         </example>
 282
 283         <para>
 284             最初にレジストリにアクセスした後でクラス名を設定しようとすると、
 285             レジストリは <classname>Zend_Exception</classname> をスローします。静的レジストリのクラス名は、
 286             アプリケーションの起動ファイルで指定することをお勧めします。
 287         </para>
 288
 289     </sect2>
 290
 291     <sect2 id="zend.registry.using.unsetting">
 292
 293         <title>静的レジストリの削除</title>
 294
 295         <para>
 296             通常は不要ですが、レジストリの静的インスタンスを削除することもできます。
 297             その際には、静的メソッド <methodname>_unsetInstance()</methodname>
 298             を使用します。
 299         </para>
 300
 301         <warning>
 302             <title>データを失うリスク</title>
 303             <para>
 304                 <methodname>_unsetInstance()</methodname> を使用すると、
 305                 静的レジストリ内の全データが破棄され、
 306                 復旧することはできません。
 307             </para>
 308         </warning>
 309
 310         <para>
 311             このメソッドを使用するのは、たとえば、
 312             シングルトンレジストリオブジェクトを初期化した後で
 313             <methodname>setInstance()</methodname> や <methodname>setClassName()</methodname>
 314             を使用する場合です。シングルトンインスタンスを削除することで、
 315             シングルトンレジストリオブジェクトを設定した後であっても
 316             これらのメソッドを使用できるようになります。特別な場合を除き、
 317             <classname>Zend_Registry</classname> をこの方式で使うことは推奨しません。
 318         </para>
 319
 320         <example id="zend.registry.using.unsetting.example">
 321             <title>_unsetInstance() メソッドの例</title>
 322             <programlisting language="php"><![CDATA[
 323 Zend_Registry::set('index', $value);
 324
 325 Zend_Registry::_unsetInstance();
 326
 327 // クラスを変更します
 328 Zend_Registry::setClassName('My_Registry');
 329
 330 Zend_Registry::set('index', $value);
 331 ]]></programlisting>
 332         </example>
 333
 334     </sect2>
 335
 336 </sect1>
 337 <!--
 338 vim:se ts=4 sw=4 et:
 339 -->