documentation/manual/en/module_specs/Zend_Tool_Framework-Extending.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.tool.framework.extending">
   4     <title>Extending and Configuring Zend_Tool_Framework</title>
   5
   6     <sect2 id="zend.tool.framework.console-client">
   7         <title>Customizing Zend_Tool Console Client</title>
   8
   9         <para>
  10             As of Zend Framework 1.9, <classname>Zend_Tool_Framework</classname> allows developers
  11             to store information, provider specific configuration values, and custom files in a
  12             special location on the developers machine. These configuration values and files can be
  13             used by providers to extend functionality, customize functionality, or any other reasons
  14             a provider sees fit.
  15         </para>
  16
  17         <para>
  18             The primary purpose, and the purpose most immediately used by existing providers is to
  19             allow developers to customize the way the "out of the box" providers do work.
  20         </para>
  21
  22         <para>
  23             One of the more commonly requested features is to be able to provide custom project
  24             profiles to <classname>Zend_Tool_Project</classname>'s Project Provider. This would
  25             allow developers to store a custom profile in a special place that can be used
  26             repeatedly by the <classname>Zend_Tool</classname> system in order to build custom
  27             profiles. Another commonly requested feature is to be able to configure the behavior of
  28             providers with a configuration setting. In order to achieve this, not only do we have to
  29             have a <classname>Zend_Tool</classname> configuration file, but we also have to have a
  30             place to find this configuration file.
  31         </para>
  32
  33         <sect3 id="zend.tool.framework.console-client.home-directory">
  34             <title>The Home Directory</title>
  35
  36             <para>
  37                 Before the Console Client can start searching for a <classname>Zend_Tool</classname>
  38                 configuration file or a local storage directory, it must first be able to identify
  39                 where the "home directory" is located.
  40             </para>
  41
  42             <para>
  43                 On *nix-based machines, <acronym>PHP</acronym> will be populated with an environment
  44                 variable named <constant>HOME</constant> with a path to the current users home
  45                 directory. Typically, this path will be very similar to
  46                 <filename>/home/myusername</filename>.
  47             </para>
  48
  49             <para>
  50                 On Windows-based machines, <acronym>PHP</acronym> will typically be populated with
  51                 an environment variable named <constant>HOMEPATH</constant> with the current users
  52                 home directory. This directory is usually found in either
  53                 <filename>C:\Documents and Settings\Username\</filename>, or in Vista at
  54                 <filename>C:\Users\Username</filename>.
  55             </para>
  56
  57             <para>
  58                 If either a home directory cannot be found, or you wish to change the location of
  59                 where <classname>Zend_Tool_Framework</classname> Console Client finds the home
  60                 directory, you can provide an environment variable named
  61                 <constant>ZF_HOME</constant> to specify where to find the home directory.
  62             </para>
  63         </sect3>
  64
  65         <sect3 id="zend.tool.framework.console-client.local-storage">
  66             <title>Local Storage</title>
  67
  68             <para>
  69                 Once a home directory can be located, <classname>Zend_Tool_Framework</classname>'s
  70                 Console Client can either autodiscover the local storage directory, or it can be
  71                 told where to expect the local storage directory.
  72             </para>
  73
  74             <para>
  75                 Assuming the home directory has been found (here noted as <varname>$HOME</varname>),
  76                 the Console Client will then look for the local storage directory in
  77                 <filename>$HOME/.zf/</filename>. If found, it will set the local storage directory
  78                 to this location.
  79             </para>
  80
  81             <para>
  82                 If the directory cannot be found, or the developer wishes to override this location,
  83                 that can be done by setting an environment variable. Regardless if
  84                 <varname>$HOME</varname> has been previously set or not, the developer may supply
  85                 the environment variable <constant>ZF_STORAGE_DIR</constant>.
  86             </para>
  87
  88             <para>
  89                 Once the path to a local storage directory is found, the directory
  90                 <emphasis>must</emphasis> exist for it to be passed into the
  91                 <classname>Zend_Tool_Framework</classname> runtime, as it will not be created for
  92                 you.
  93             </para>
  94         </sect3>
  95
  96         <sect3 id="zend.tool.framework.console-client.configuration-file">
  97             <title>User Configuration</title>
  98
  99             <para>
 100                 Like local storage, once a home directory can be located,
 101                 <classname>Zend_Tool_Framework</classname>'s Console Client can then either attempt
 102                 to autodiscover the path to a configuration file, or it can be told specifically
 103                 where to find the configuration file.
 104             </para>
 105
 106             <para>
 107                 Assuming the home directory has been found (here noted as <varname>$HOME</varname>),
 108                 the Console Client will then attempt to look for the existence of a configuration
 109                 file located at <filename>$HOME/.zf.ini</filename>. This file, if found, will be
 110                 used as the configuration file for <classname>Zend_Tool_Framework</classname>.
 111             </para>
 112
 113             <para>
 114                 If that location does not exist, but a local storage directory does, then the
 115                 Console Client will then attempt to locate the configuration file within the local
 116                 storage directory. Assuming the local storage directory exists in
 117                 <varname>$LOCAL_STORAGE</varname>, then if a file exists as
 118                 <filename>$LOCAL_STORAGE/zf.ini</filename>, it will be found by the Console Client
 119                 and utilized as the <classname>Zend_Tool_Framework</classname> configuration file.
 120             </para>
 121
 122             <para>
 123                 If the file cannot be autodiscovered or the developer wishes to specify the location
 124                 of location of the configuration file, the developer can do so by setting an
 125                 environment variable. If the environment variable
 126                 <constant>ZF_CONFIG_FILE</constant> is set, then its value will be used as the
 127                 location of the configuration file to use with the Console Client. The
 128                 <constant>ZF_CONFIG_FILE</constant> can point to any
 129                 <classname>Zend_Config</classname> readable <acronym>INI</acronym>,
 130                 <acronym>XML</acronym> or <acronym>PHP</acronym> File.
 131             </para>
 132
 133             <para>
 134                 If the file does not exist in either the autodiscovered or the provided location, it
 135                 will not be used as <classname>Zend_Tool_Framework</classname> does not attempt to
 136                 create the file automatically.
 137             </para>
 138         </sect3>
 139
 140         <sect3 id="zend.tool.framework.console-client.configuration-content">
 141             <title>User Configuration File Content</title>
 142
 143             <para>
 144                 The configuration file should be structured as a <classname>Zend_Config</classname>
 145                 configuration file, in <acronym>INI</acronym> format, and without any sections being
 146                 defined. First level keys should be used by the provider searching for a specific
 147                 value. For example, if the "Project" provider is expecting a "profiles" directory,
 148                 then it should typically be understood that it will search for the following
 149                 <acronym>INI</acronym> key value pair:
 150             </para>
 151
 152             <programlisting language="php"><![CDATA[
 153 project.profile = some/path/to/some-directory
 154 ]]></programlisting>
 155
 156             <para>
 157                 The only reserved <acronym>INI</acronym> prefix is the value "php". The "php" prefix
 158                 to values will be reserved to store names and values of runtime settable
 159                 <acronym>PHP</acronym> values, such as <property>include_path</property> or
 160                 <property>error_reporting</property>. To override the
 161                 <property>include_path</property> and <property>error_reporting</property> with an
 162                 <acronym>INI</acronym> value, a developer would set:
 163             </para>
 164
 165             <programlisting language="php"><![CDATA[
 166 php.include_path = "/path/to/includes1:/path/to/includes2"
 167 php.error_reporting = 1
 168 ]]></programlisting>
 169
 170             <important>
 171                 <para>
 172                     The reserved prefix "php" only works with <acronym>INI</acronym> files. You
 173                     can't set <acronym>PHP</acronym> <acronym>INI</acronym> values with
 174                     <acronym>PHP</acronym> or <acronym>XML</acronym> config.
 175                 </para>
 176             </important>
 177         </sect3>
 178     </sect2>
 179 </sect1>