documentation/manual/en/module_specs/Zend_Application-CoreFunctionality-Resource_ResourceAbstract.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.application.core-functionality.resource-resourceabstract">
   4     <title>Zend_Application_Resource_ResourceAbstract</title>
   5
   6     <para>
   7         <classname>Zend_Application_Resource_ResourceAbstract</classname> is an abstract
   8         class implementing <link
   9             linkend="zend.application.core-functionality.resource-resource">Zend_Application_Resource_Resource</link>,
  10         and is a good starting point for creating your own custom plugin
  11         resources.
  12     </para>
  13
  14     <para>
  15         Note: this abstract class does not implement the <methodname>init()</methodname>
  16         method; this is left for definition in concrete extensions of the
  17         class.
  18     </para>
  19
  20     <table id="zend.application.core-functionality.resource-resourceabstract.api">
  21         <title>Zend_Application_Resource_ResourceAbstract Methods</title>
  22
  23         <tgroup cols="4">
  24             <thead>
  25                 <row>
  26                     <entry>Method</entry>
  27                     <entry>Return Value</entry>
  28                     <entry>Parameters</entry>
  29                     <entry>Description</entry>
  30                 </row>
  31             </thead>
  32
  33             <tbody>
  34                 <row>
  35                     <entry><methodname>__construct($options = null)</methodname></entry>
  36                     <entry><type>Void</type></entry>
  37                     <entry>
  38                         <itemizedlist>
  39                             <listitem>
  40                                 <para>
  41                                     <varname>$options</varname>: <emphasis>optional</emphasis>.
  42                                     Options with which to set resource state.
  43                                 </para>
  44                             </listitem>
  45                         </itemizedlist>
  46                     </entry>
  47
  48                     <entry>
  49                         <para>
  50                             The constructor should allow passing options with which to initialize
  51                             state.
  52                         </para>
  53                     </entry>
  54                 </row>
  55
  56                 <row>
  57                     <entry>
  58                         <methodname>setBootstrap(Zend_Application_Bootstrap_Bootstrapper
  59                             $bootstrap)</methodname>
  60                     </entry>
  61
  62                     <entry><classname>Zend_Application_Resource_ResourceAbstract</classname></entry>
  63
  64                     <entry>
  65                         <itemizedlist>
  66                             <listitem>
  67                                 <para>
  68                                     <varname>$bootstrap</varname>: <emphasis>required</emphasis>.
  69                                     Parent bootstrap initializing this resource.
  70                                 </para>
  71                             </listitem>
  72                         </itemizedlist>
  73                     </entry>
  74
  75                     <entry>
  76                         <para>Should allow registering the parent bootstrap object.</para>
  77                     </entry>
  78                 </row>
  79
  80                 <row>
  81                     <entry><methodname>getBootstrap()</methodname></entry>
  82                     <entry><classname>Zend_Application_Bootstrap_Bootstrapper</classname></entry>
  83                     <entry>N/A</entry>
  84                     <entry><para>Retrieve the registered bootstrap instance.</para></entry>
  85                 </row>
  86
  87                 <row>
  88                     <entry><methodname>setOptions(array $options)</methodname></entry>
  89                     <entry><classname>Zend_Application_Resource_ResourceAbstract</classname></entry>
  90
  91                     <entry>
  92                         <itemizedlist>
  93                             <listitem>
  94                                 <para>
  95                                     <varname>$options</varname>: <emphasis>required</emphasis>.
  96                                     Options with which to set state.
  97                                 </para>
  98                             </listitem>
  99                         </itemizedlist>
 100                     </entry>
 101
 102                     <entry><para>Set resource state.</para></entry>
 103                 </row>
 104
 105                 <row>
 106                     <entry><methodname>getOptions()</methodname></entry>
 107                     <entry><type>Array</type></entry>
 108                     <entry>N/A</entry>
 109                     <entry><para>Retrieve registered options.</para></entry>
 110                 </row>
 111             </tbody>
 112         </tgroup>
 113     </table>
 114
 115     <sect3 id="zend.application.core-functionality.resource-resourceabstract.names">
 116         <title>Resource Names</title>
 117
 118         <para>
 119             When registering plugin resources, one issue that arises is how you
 120             should refer to them from the parent bootstrap class. There are
 121             three different mechanisms that may be used, depending on how you
 122             have configured the bootstrap and its plugin resources.
 123         </para>
 124
 125         <para>
 126             First, if your plugins are defined within a defined prefix path, you
 127             may refer to them simply by their "short name" -- i.e., the portion
 128             of the class name following the class prefix. As an example, the
 129             class "<classname>Zend_Application_Resource_View</classname>" may be referenced as
 130             simply "View", as the prefix path "<classname>Zend_Application_Resource</classname>"
 131             is already registered. You may register them using the full class name or the
 132             short name:
 133         </para>
 134
 135         <programlisting language="php"><![CDATA[
 136 $app = new Zend_Application(APPLICATION_ENV, array(
 137     'pluginPaths' => array(
 138         'My_Resource' => 'My/Resource/',
 139     ),
 140     'resources' => array(
 141         // if the following class exists:
 142         'My_Resource_View' => array(),
 143
 144         // then this is equivalent:
 145         'View' => array(),
 146     ),
 147 ));
 148 ]]></programlisting>
 149
 150         <para>
 151             In each case, you can then bootstrap the resource and retrieve it
 152             later using the short name:
 153         </para>
 154
 155         <programlisting language="php"><![CDATA[
 156 $bootstrap->bootstrap('view');
 157 $view = $bootstrap->getResource('view');
 158 ]]></programlisting>
 159
 160         <para>
 161             Second, if no matching plugin path is defined, you may still pass a
 162             resource by the full class name. In this case, you can reference it
 163             using the resource's full class name:
 164         </para>
 165
 166         <programlisting language="php"><![CDATA[
 167 $app = new Zend_Application(APPLICATION_ENV, array(
 168     'resources' => array(
 169         // This will load the standard 'View' resource:
 170         'View' => array(),
 171
 172         // While this loads a resource with a specific class name:
 173         'My_Resource_View' => array(),
 174     ),
 175 ));
 176 ]]></programlisting>
 177
 178         <para>
 179             Obviously, this makes referencing the resource much more verbose:
 180         </para>
 181
 182         <programlisting language="php"><![CDATA[
 183 $bootstrap->bootstrap('My_Resource_View');
 184 $view = $bootstrap->getResource('My_Resource_View');
 185 ]]></programlisting>
 186
 187         <para>
 188             This brings us to the third option. You can specify an explicit name
 189             that a given resource class will register as. This can be done by
 190             adding a public <varname>$_explicitType</varname> property to the resource
 191             plugin class, with a string value; that value will then be used
 192             whenever you wish to reference the plugin resource via the
 193             bootstrap. As an example, let's define our own view class:
 194         </para>
 195
 196         <programlisting language="php"><![CDATA[
 197 class My_Resource_View extends Zend_Application_Resource_ResourceAbstract
 198 {
 199     public $_explicitType = 'My_View';
 200
 201     public function init()
 202     {
 203         // do some initialization...
 204     }
 205 }
 206 ]]></programlisting>
 207
 208         <para>
 209             We can then bootstrap that resource or retrieve it by the name
 210             "<classname>My_View</classname>":
 211         </para>
 212
 213         <programlisting language="php"><![CDATA[
 214 $bootstrap->bootstrap('My_View');
 215 $view = $bootstrap->getResource('My_View');
 216 ]]></programlisting>
 217
 218         <para>
 219             Using these various naming approaches, you can override existing
 220             resources, add your own, mix multiple resources to achieve complex
 221             initialization, and more.
 222         </para>
 223     </sect3>
 224 </sect2>