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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.application.core-functionality.application">
   4     <title>Zend_Application</title>
   5
   6     <para>
   7         <classname>Zend_Application</classname> provides the base functionality of the
   8         component, and the entry point to your Zend Framework application. It's
   9         purpose is two-fold: to setup the <acronym>PHP</acronym> environment (including
  10         autoloading), and to execute your application bootstrap.
  11     </para>
  12
  13     <para>
  14         Typically, you will pass all configuration to the
  15         <classname>Zend_Application</classname> constructor, but you can also configure
  16         the object entirely using its own methods. This reference is intended to
  17         illustrate both use cases.
  18     </para>
  19
  20     <table id="zend.application.core-functionality.application.api.options">
  21         <title>Zend_Application options</title>
  22
  23         <tgroup cols="2">
  24             <thead>
  25                 <row>
  26                     <entry>Option</entry>
  27                     <entry>Description</entry>
  28                 </row>
  29             </thead>
  30
  31             <tbody>
  32                 <row>
  33                     <entry><emphasis><property>phpSettings</property></emphasis></entry>
  34
  35                     <entry>
  36                         <para>
  37                             Array of <filename>php.ini</filename> settings to use. Keys should be
  38                             the <filename>php.ini</filename> keys.
  39                         </para>
  40                     </entry>
  41                 </row>
  42
  43                 <row>
  44                     <entry><emphasis><property>includePaths</property></emphasis></entry>
  45
  46                     <entry>
  47                         <para>
  48                             Additional paths to prepend to the <emphasis>include_path</emphasis>.
  49                             Should be an array of paths.
  50                         </para>
  51                     </entry>
  52                 </row>
  53
  54                 <row>
  55                     <entry><emphasis><property>autoloaderNamespaces</property></emphasis></entry>
  56
  57                     <entry>
  58                         <para>
  59                             Array of additional namespaces to register with the
  60                             <classname>Zend_Loader_Autoloader</classname> instance.
  61                         </para>
  62                     </entry>
  63                 </row>
  64
  65                 <row>
  66                     <entry><emphasis><property>bootstrap</property></emphasis></entry>
  67
  68                     <entry>
  69                         <para>
  70                             Either the string path to the bootstrap class, or an array
  71                             with elements for the 'path' and 'class' for the application
  72                             bootstrap.
  73                         </para>
  74                     </entry>
  75                 </row>
  76             </tbody>
  77         </tgroup>
  78     </table>
  79
  80     <note>
  81         <title>Option names</title>
  82
  83         <para>
  84             Please note that option names are case insensitive.
  85         </para>
  86     </note>
  87
  88     <table id="zend.application.core-functionality.application.api.table">
  89         <title>Zend_Application Methods</title>
  90
  91         <tgroup cols="4">
  92             <thead>
  93                 <row>
  94                     <entry>Method</entry>
  95                     <entry>Return Value</entry>
  96                     <entry>Parameters</entry>
  97                     <entry>Description</entry>
  98                 </row>
  99             </thead>
 100
 101             <tbody>
 102                 <row>
 103                     <entry>
 104                         <methodname>__construct($environment, $options = null)</methodname>
 105                     </entry>
 106
 107                     <entry><type>Void</type></entry>
 108
 109                     <entry>
 110                         <itemizedlist>
 111                             <listitem>
 112                                 <para>
 113                                     <varname>$environment</varname>: <emphasis>required</emphasis>,.
 114                                     String representing the current application
 115                                     environment. Typical strings might include
 116                                     "development", "testing", "qa", or
 117                                     "production", but will be defined by your
 118                                     organizational requirements.
 119                                 </para>
 120                             </listitem>
 121
 122                             <listitem>
 123                                 <para>
 124                                     <varname>$options</varname>: <emphasis>optional</emphasis>.
 125                                     Argument may be one of the following values:
 126                                 </para>
 127
 128                                 <itemizedlist>
 129                                     <listitem>
 130                                         <para>
 131                                             <emphasis><type>String</type></emphasis>: path to
 132                                             a <classname>Zend_Config</classname> file to load
 133                                             as configuration for your application.
 134                                             <varname>$environment</varname> will be used
 135                                             to determine what section of the
 136                                             configuration to pull.
 137                                         </para>
 138
 139                                         <para>
 140                                             As of 1.10, you may also pass multiple paths containing
 141                                             config files to be merged into a single configuration.
 142                                             This assists in reducing config duplication across many
 143                                             contexts which share common settings (e.g. configs for
 144                                             <acronym>HTTP</acronym>, or <acronym>CLI</acronym>, each
 145                                             sharing some characteristics but with their own
 146                                             conflicting values for others) or merely splitting a
 147                                             long configuration across many smaller categorised
 148                                             files. The parameter in this case is an array with a
 149                                             single key "configs" whose value is an array of the
 150                                             files to merge. Note: this means you either pass a
 151                                             literal path, or
 152                                             <command>array("configs"=>array("/path1","/path2"[,...]));</command>.
 153                                         </para>
 154                                     </listitem>
 155
 156                                     <listitem>
 157                                         <para>
 158                                             <emphasis><type>Array</type></emphasis>: associative
 159                                             array of configuration data for your application.
 160                                         </para>
 161                                     </listitem>
 162
 163                                     <listitem>
 164                                         <para>
 165                                             <emphasis><classname>Zend_Config</classname></emphasis>:
 166                                             configuration object instance.
 167                                         </para>
 168                                     </listitem>
 169                                 </itemizedlist>
 170                             </listitem>
 171                         </itemizedlist>
 172                     </entry>
 173
 174                     <entry>
 175                         <para>
 176                             Constructor. Arguments are as described, and will be
 177                             used to set initial object state. An instance of
 178                             <classname>Zend_Loader_Autoloader</classname> is registered
 179                             during instantiation. Options passed to the
 180                             constructor are passed to <methodname>setOptions()</methodname>.
 181                         </para>
 182                     </entry>
 183                 </row>
 184
 185                 <row>
 186                     <entry><methodname>getEnvironment()</methodname></entry>
 187                     <entry><type>String</type></entry>
 188                     <entry>N/A</entry>
 189
 190                     <entry>
 191                         <para>Retrieve the environment string passed to the constructor.</para>
 192                     </entry>
 193                 </row>
 194
 195                 <row>
 196                     <entry><methodname>getAutoloader()</methodname></entry>
 197                     <entry><classname>Zend_Loader_Autoloader</classname></entry>
 198                     <entry>N/A</entry>
 199
 200                     <entry>
 201                         <para>
 202                             Retrieve the <classname>Zend_Loader_Autoloader</classname>
 203                             instance registered during instantiation.
 204                         </para>
 205                     </entry>
 206                 </row>
 207
 208                 <row>
 209                     <entry><methodname>setOptions(array $options)</methodname></entry>
 210                     <entry><classname>Zend_Application</classname></entry>
 211
 212                     <entry>
 213                         <itemizedlist>
 214                             <listitem>
 215                                 <para>
 216                                     <varname>$options</varname>: <emphasis>required</emphasis>.
 217                                     An array of application options.
 218                                 </para>
 219                             </listitem>
 220                         </itemizedlist>
 221                     </entry>
 222
 223                     <entry>
 224                         <para>
 225                             All options are stored internally, and calling the
 226                             method multiple times will merge options. Options
 227                             matching the various setter methods will be passed
 228                             to those methods. As an example, the option
 229                             "phpSettings" will then be passed to
 230                             <methodname>setPhpSettings()</methodname>. (Option names are
 231                             case insensitive.)
 232                         </para>
 233                     </entry>
 234                 </row>
 235
 236                 <row>
 237                     <entry><methodname>getOptions()</methodname></entry>
 238                     <entry><type>Array</type></entry>
 239                     <entry>N/A</entry>
 240
 241                     <entry>
 242                         <para>
 243                             Retrieve all options used to initialize the object;
 244                             could be used to cache <classname>Zend_Config</classname>
 245                             options to a serialized format between requests.
 246                         </para>
 247                     </entry>
 248                 </row>
 249
 250                 <row>
 251                     <entry><methodname>hasOption($key)</methodname></entry>
 252                     <entry><type>Boolean</type></entry>
 253                     <entry>
 254                         <itemizedlist>
 255                             <listitem>
 256                                 <para>
 257                                     <varname>$key</varname>: String option key to lookup
 258                                 </para>
 259                             </listitem>
 260                         </itemizedlist>
 261                     </entry>
 262
 263                     <entry>
 264                         <para>
 265                             Determine whether or not an option with the
 266                             specified key has been registered. Keys are case insensitive.
 267                         </para>
 268                     </entry>
 269                 </row>
 270
 271                 <row>
 272                     <entry><methodname>getOption($key)</methodname></entry>
 273                     <entry><type>Mixed</type></entry>
 274                     <entry>
 275                         <itemizedlist>
 276                             <listitem>
 277                                 <para><varname>$key</varname>: String option key to lookup</para>
 278                             </listitem>
 279                         </itemizedlist>
 280                     </entry>
 281
 282                     <entry>
 283                         <para>
 284                             Retrieve the option value of a given key. Returns
 285                             <constant>NULL</constant> if the key does not exist.
 286                         </para>
 287                     </entry>
 288                 </row>
 289
 290                 <row>
 291                     <entry>
 292                         <methodname>setPhpSettings(array $settings, $prefix = '')</methodname>
 293                     </entry>
 294
 295                     <entry><classname>Zend_Application</classname></entry>
 296
 297                     <entry>
 298                         <itemizedlist>
 299                             <listitem>
 300                                 <para>
 301                                     <varname>$settings</varname>: <emphasis>required</emphasis>.
 302                                     Associative array of <acronym>PHP</acronym>
 303                                     <acronym>INI</acronym> settings.
 304                                 </para>
 305                             </listitem>
 306
 307                             <listitem>
 308                                 <para>
 309                                     <varname>$prefix</varname>: <emphasis>optional</emphasis>.
 310                                     String prefix with which to prepend option keys. Used
 311                                     internally to allow mapping nested arrays to dot-separated
 312                                     <filename>php.ini</filename> keys. In normal usage, this
 313                                     argument should never be passed by a user.
 314                                 </para>
 315                             </listitem>
 316                         </itemizedlist>
 317                     </entry>
 318
 319                     <entry>
 320                         <para>
 321                             Set run-time <filename>php.ini</filename> settings. Dot-separated
 322                             settings may be nested hierarchically (which may occur
 323                             with <acronym>INI</acronym> <classname>Zend_Config</classname> files)
 324                             via an array-of-arrays, and will still resolve correctly.
 325                         </para>
 326                     </entry>
 327                 </row>
 328
 329                 <row>
 330                     <entry>
 331                         <methodname>setAutoloaderNamespaces(array $namespaces)</methodname>
 332                     </entry>
 333
 334                     <entry><classname>Zend_Application</classname></entry>
 335
 336                     <entry>
 337                         <itemizedlist>
 338                             <listitem>
 339                                 <para>
 340                                     <varname>$namespaces</varname>: <emphasis>required</emphasis>.
 341                                     Array of strings representing the namespaces to
 342                                     register with the <classname>Zend_Loader_Autoloader</classname>
 343                                     instance.
 344                                 </para>
 345                             </listitem>
 346                         </itemizedlist>
 347                     </entry>
 348
 349                     <entry>
 350                         <para>
 351                             Register namespaces with the
 352                             <classname>Zend_Loader_Autoloader</classname> instance.
 353                         </para>
 354                     </entry>
 355                 </row>
 356
 357                 <row>
 358                     <entry><methodname>setBootstrap($path, $class = null)</methodname></entry>
 359                     <entry><classname>Zend_Application</classname></entry>
 360
 361                     <entry>
 362                         <itemizedlist>
 363                             <listitem>
 364                                 <para>
 365                                     <varname>$path</varname>: <emphasis>required</emphasis>. May be
 366                                     either a
 367                                     <classname>Zend_Application_Bootstrap_Bootstrapper</classname>
 368                                     instance, a string path to the bootstrap class, an
 369                                     associative array of classname =&gt; filename, or an associative
 370                                     array with the keys 'class' and 'path'.
 371                                 </para>
 372                             </listitem>
 373
 374                             <listitem>
 375                                 <para>
 376                                     <varname>$class</varname>: <emphasis>optional</emphasis>.
 377                                     If <varname>$path</varname> is a string,
 378                                     <varname>$class</varname> may be specified, and should
 379                                     be a string class name of the class contained in
 380                                     the file represented by path.
 381                                 </para>
 382                             </listitem>
 383                         </itemizedlist>
 384                     </entry>
 385                 </row>
 386
 387                 <row>
 388                     <entry><methodname>getBootstrap()</methodname></entry>
 389
 390                     <entry>
 391                         <constant>NULL</constant> |
 392                         <classname>Zend_Application_Bootstrap_Bootstrapper</classname>
 393                     </entry>
 394
 395                     <entry>N/A</entry>
 396                     <entry><para>Retrieve the registered bootstrap instance.</para></entry>
 397                 </row>
 398
 399                 <row>
 400                     <entry><methodname>bootstrap()</methodname></entry>
 401                     <entry><type>Void</type></entry>
 402                     <entry>N/A</entry>
 403                     <entry>
 404                         <para>
 405                             Call the bootstrap's <methodname>bootstrap()</methodname>
 406                             method to bootstrap the application.
 407                         </para>
 408                     </entry>
 409                 </row>
 410
 411                 <row>
 412                     <entry><methodname>run()</methodname></entry>
 413                     <entry><type>Void</type></entry>
 414                     <entry>N/A</entry>
 415                     <entry>
 416                         <para>
 417                             Call the bootstrap's <methodname>run()</methodname>
 418                             method to dispatch the application.
 419                         </para>
 420                     </entry>
 421                 </row>
 422             </tbody>
 423         </tgroup>
 424     </table>
 425 </sect2>