documentation/manual/en/module_specs/Zend_Registry.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.registry.using">
   4     <title>Using the Registry</title>
   5
   6     <para>
   7         A registry is a container for storing objects and values in the
   8         application space. By storing the value in a registry, the same
   9         object is always available throughout your application.
  10         This mechanism is an alternative to using global storage.
  11     </para>
  12
  13     <para>
  14         The typical method to use registries with Zend Framework is through static methods in the
  15         <classname>Zend_Registry</classname> class. Alternatively, the registry can be used as an
  16         array object, so you can access elements stored within it with a convenient array-like
  17         interface.
  18     </para>
  19
  20     <sect2 id="zend.registry.using.storing">
  21         <title>Setting Values in the Registry</title>
  22
  23         <para>
  24             Use the static method <methodname>set()</methodname> to store an entry in the registry.
  25         </para>
  26
  27         <example id="zend.registry.using.storing.example">
  28             <title>Example of set() Method Usage</title>
  29
  30             <programlisting language="php"><![CDATA[
  31 Zend_Registry::set('index', $value);
  32 ]]></programlisting>
  33         </example>
  34
  35         <para>
  36             The value returned can be an object, an array, or a scalar.
  37             You can change the value stored in a specific entry of
  38             the registry by calling the <methodname>set()</methodname> method to set the entry
  39             to a new value.
  40         </para>
  41
  42         <para>
  43             The index can be a scalar (<constant>NULL</constant>, string, or number), like an
  44             ordinary array.
  45         </para>
  46     </sect2>
  47
  48     <sect2 id="zend.registry.using.retrieving">
  49         <title>Getting Values from the Registry</title>
  50
  51         <para>
  52             To retrieve an entry from the registry, use the static
  53             <methodname>get()</methodname> method.
  54         </para>
  55
  56         <example id="zend.registry.using.retrieving.example">
  57             <title>Example of get() Method Usage</title>
  58
  59             <programlisting language="php"><![CDATA[
  60 $value = Zend_Registry::get('index');
  61 ]]></programlisting>
  62         </example>
  63
  64         <para>
  65             The <methodname>getInstance()</methodname> method returns the singleton registry object.
  66             This registry object is iterable, making all values stored in the registry easily
  67             accessible.
  68         </para>
  69
  70         <example id="zend.registry.using.retrieving.example-iterating">
  71             <title>Example of Iterating over the Registry</title>
  72
  73             <programlisting language="php"><![CDATA[
  74 $registry = Zend_Registry::getInstance();
  75
  76 foreach ($registry as $index => $value) {
  77     echo "Registry index $index contains:\n";
  78     var_dump($value);
  79 }
  80 ]]></programlisting>
  81         </example>
  82     </sect2>
  83
  84     <sect2 id="zend.registry.using.constructing">
  85         <title>Constructing a Registry Object</title>
  86
  87         <para>
  88             In addition to accessing the static registry via
  89             static methods, you can create an instance directly and
  90             use it as an object.
  91         </para>
  92
  93         <para>
  94             The registry instance you access through the
  95             static methods is simply one such instance. It is
  96             for convenience that it is stored statically, so that it is
  97             accessible from anywhere in an application.
  98         </para>
  99
 100         <para>
 101             Use the traditional <code>new</code> operator to instantiate
 102             <classname>Zend_Registry</classname>. Instantiating <classname>Zend_Registry</classname>
 103             using its constructor also makes initializing the entries in the registry simple by
 104             taking an associative array as an argument.
 105         </para>
 106
 107         <example id="zend.registry.using.constructing.example">
 108             <title>Example of Constructing a Registry</title>
 109
 110             <programlisting language="php"><![CDATA[
 111 $registry = new Zend_Registry(array('index' => $value));
 112 ]]></programlisting>
 113         </example>
 114
 115         <para>
 116             Once such a <classname>Zend_Registry</classname> object is instantiated,
 117             you can use it by calling any array object method or by setting it
 118             as the singleton instance for <classname>Zend_Registry</classname> with the static
 119             method <methodname>setInstance()</methodname>.
 120         </para>
 121
 122         <example id="zend.registry.using.constructing.example-setinstance">
 123             <title>Example of Initializing the Singleton Registry</title>
 124
 125             <programlisting language="php"><![CDATA[
 126 $registry = new Zend_Registry(array('index' => $value));
 127
 128 Zend_Registry::setInstance($registry);
 129 ]]></programlisting>
 130         </example>
 131
 132         <para>
 133             The <methodname>setInstance()</methodname> method throws a
 134             <classname>Zend_Exception</classname> if the static registry has already been
 135             initialized.
 136         </para>
 137     </sect2>
 138
 139     <sect2 id="zend.registry.using.array-access">
 140         <title>Accessing the Registry as an Array</title>
 141
 142         <para>
 143             If you have several values to get or set, you may find it
 144             convenient to access the registry with array notation.
 145         </para>
 146
 147         <example id="zend.registry.using.array-access.example">
 148             <title>Example of Array Access</title>
 149
 150             <programlisting language="php"><![CDATA[
 151 $registry = Zend_Registry::getInstance();
 152
 153 $registry['index'] = $value;
 154
 155 var_dump( $registry['index'] );
 156 ]]></programlisting>
 157         </example>
 158     </sect2>
 159
 160     <sect2 id="zend.registry.using.array-object">
 161         <title>Accessing the Registry as an Object</title>
 162
 163         <para>
 164             You may also find it convenient to access the registry
 165             in an object-oriented fashion by using index names as object
 166             properties.
 167             You must specifically construct the registry
 168             object using the <constant>ArrayObject::ARRAY_AS_PROPS</constant> option
 169             and initialize the static instance to enable this functionality.
 170
 171             <note>
 172                 <para>You must set the <constant>ArrayObject::ARRAY_AS_PROPS</constant> option
 173                 <emphasis>before</emphasis> the static registry has been accessed for
 174                 the first time.</para>
 175             </note>
 176         </para>
 177
 178         <warning>
 179             <title>Known Issues with the ArrayObject::ARRAY_AS_PROPS Option</title>
 180
 181             <para>
 182                 Some versions of <acronym>PHP</acronym> have proven very buggy when using the
 183                 registry with the <constant>ArrayObject::ARRAY_AS_PROPS</constant> option.
 184             </para>
 185         </warning>
 186
 187         <example id="zend.registry.using.array-object.example">
 188             <title>Example of Object Access</title>
 189
 190             <programlisting language="php"><![CDATA[
 191 // in your application bootstrap:
 192 $registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS)
 193 Zend_Registry::setInstance($registry);
 194 $registry->tree = 'apple';
 195
 196 .
 197 .
 198 .
 199
 200 // in a different function, elsewhere in your application:
 201 $registry = Zend_Registry::getInstance();
 202
 203 echo $registry->tree; // echo's "apple"
 204
 205 $registry->index = $value;
 206
 207 var_dump($registry->index);
 208 ]]></programlisting>
 209         </example>
 210     </sect2>
 211
 212     <sect2 id="zend.registry.using.isset">
 213         <title>Querying if an Index Exists</title>
 214
 215         <para>
 216             To find out if a particular index in the registry
 217             has been set, use the static method <methodname>isRegistered()</methodname>.
 218         </para>
 219
 220         <example id="zend.registry.using.isset.example-isregistered">
 221             <title>Example of isRegistered() Method Usage</title>
 222
 223             <programlisting language="php"><![CDATA[
 224 if (Zend_Registry::isRegistered($index)) {
 225     $value = Zend_Registry::get($index);
 226 }
 227 ]]></programlisting>
 228         </example>
 229
 230         <para>
 231             To find out if a particular index in a registry
 232             array or object has a value, use the <methodname>isset()</methodname> function
 233             as you would with an ordinary array.
 234         </para>
 235
 236         <example id="zend.registry.using.isset.example-isset">
 237             <title>Example of isset() Method Usage</title>
 238
 239             <programlisting language="php"><![CDATA[
 240 $registry = Zend_Registry::getInstance();
 241
 242 // using array access syntax
 243 if (isset($registry['index'])) {
 244     var_dump( $registry['index'] );
 245 }
 246
 247 // using object access syntax
 248 if (isset($registry->index)) {
 249     var_dump( $registry->index );
 250 }
 251 ]]></programlisting>
 252         </example>
 253     </sect2>
 254
 255     <sect2 id="zend.registry.using.subclassing">
 256         <title>Extending the Registry</title>
 257
 258         <para>
 259             The static registry is an instance of the class <classname>Zend_Registry</classname>.
 260             If you want to add functionality to the registry, you should
 261             create a class that extends <classname>Zend_Registry</classname> and
 262             specify this class to instantiate for the singleton in the static registry.
 263             Use the static method <methodname>setClassName()</methodname> to specify
 264             the class.
 265
 266             <note>
 267                 <para>The class must be a subclass of <classname>Zend_Registry</classname>.</para>
 268             </note>
 269         </para>
 270
 271         <example id="zend.registry.using.subclassing.example">
 272             <title>Example of Specifying the Singleton Registry's Class Name</title>
 273
 274             <programlisting language="php"><![CDATA[
 275 Zend_Registry::setClassName('My_Registry');
 276
 277 Zend_Registry::set('index', $value);
 278 ]]></programlisting>
 279         </example>
 280
 281         <para>
 282             The registry throws a <classname>Zend_Exception</classname> if you attempt to set the
 283             classname after the registry has been accessed for the first time.
 284             It is therefore recommended that you specify the class name for your
 285             static registry in your application bootstrap.
 286         </para>
 287     </sect2>
 288
 289     <sect2 id="zend.registry.using.unsetting">
 290         <title>Unsetting the Static Registry</title>
 291
 292         <para>
 293             Although it is not normally necessary, you can
 294             unset the singleton instance of the registry, if desired.
 295             Use the static method <methodname>_unsetInstance()</methodname> to do so.
 296         </para>
 297
 298         <warning>
 299             <title>Data Loss Risk</title>
 300
 301             <para>
 302                 When you use <methodname>_unsetInstance()</methodname>,
 303                 all data in the static registry are
 304                 discarded and cannot be recovered.
 305             </para>
 306         </warning>
 307
 308         <para>
 309             You might use this method, for example, if you want to
 310             use <methodname>setInstance()</methodname> or <methodname>setClassName()</methodname>
 311             after the singleton registry object has been initialized.
 312             Unsetting the singleton instance allows you to use these methods
 313             even after the singleton registry object has been set. Using
 314             <classname>Zend_Registry</classname> in this manner is not recommended for typical
 315             applications and environments.
 316         </para>
 317
 318         <example id="zend.registry.using.unsetting.example">
 319             <title>Example of _unsetInstance() Method Usage</title>
 320
 321             <programlisting language="php"><![CDATA[
 322 Zend_Registry::set('index', $value);
 323
 324 Zend_Registry::_unsetInstance();
 325
 326 // change the class
 327 Zend_Registry::setClassName('My_Registry');
 328
 329 Zend_Registry::set('index', $value);
 330 ]]></programlisting>
 331         </example>
 332     </sect2>
 333 </sect1>
 334 <!--
 335 vim:se ts=4 sw=4 et:
 336 -->