documentation/manual/en/module_specs/Zend_Log-Factory.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.log.factory">
   4     <title>Using the Factory to Create a Log</title>
   5
   6     <para>
   7         In addition to direct instantiation, you may also use the static
   8         <methodname>factory()</methodname> method to instantiate a Log instance, as well as to
   9         configure attached writers and their filters. Using the factory, you can attach zero or
  10         more writers. Configuration may be passed as either an array or a
  11         <classname>Zend_Config</classname> instance.
  12     </para>
  13
  14     <para>
  15         As an example:
  16     </para>
  17
  18     <programlisting language="php"><![CDATA[
  19 $logger = Zend_Log::factory(array(
  20     array(
  21         'writerName'   => 'Stream',
  22         'writerParams' => array(
  23             'stream'   => '/tmp/zend.log',
  24         ),
  25         'filterName'   => 'Priority',
  26         'filterParams' => array(
  27             'priority' => Zend_Log::WARN,
  28         ),
  29     ),
  30     array(
  31         'writerName'   => 'Firebug',
  32         'filterName'   => 'Priority',
  33         'filterParams' => array(
  34             'priority' => Zend_Log::INFO,
  35         ),
  36     ),
  37 ));
  38 ]]></programlisting>
  39
  40     <para>
  41         The above will instantiate a logger with two writers, one for writing to a local file,
  42         another for sending data to Firebug. Each has an attached priority filter, with different
  43         maximum priorities.
  44     </para>
  45
  46     <para>
  47         Each writer can be defined with the following keys:
  48     </para>
  49
  50     <variablelist>
  51         <varlistentry>
  52             <term>writerName (required)</term>
  53
  54             <listitem>
  55                 <para>
  56                     The "short" name of a log writer; the name of the log writer minus the leading
  57                     class prefix/namespace. See the "writerNamespace" entry below for more details.
  58                     Examples: "Mock", "Stream", "Firebug".
  59                 </para>
  60             </listitem>
  61         </varlistentry>
  62
  63         <varlistentry>
  64             <term>writerParams (optional)</term>
  65
  66             <listitem>
  67                 <para>
  68                     An associative array of parameters to use when instantiating the log writer.
  69                     Each log writer's <methodname>factory()</methodname> method will map these to
  70                     constructor arguments, as noted below.
  71                 </para>
  72             </listitem>
  73         </varlistentry>
  74
  75         <varlistentry>
  76             <term>writerNamespace (optional)</term>
  77
  78             <listitem>
  79                 <para>
  80                     The class prefix/namespace to use when constructing the final log writer
  81                     classname. By default, if this is not provided, "Zend_Log_Writer" is assumed;
  82                     however, you can pass your own namespace if you are using a custom log writer.
  83                 </para>
  84             </listitem>
  85         </varlistentry>
  86
  87         <varlistentry>
  88             <term>filterName (optional)</term>
  89
  90             <listitem>
  91                 <para>
  92                     The "short" name of a filter to use with the given log writer; the name of the
  93                     filter minus the leading class prefix/namespace. See the "filterNamespace" entry
  94                     below for more details. Examples: "Message", "Priority".
  95                 </para>
  96             </listitem>
  97         </varlistentry>
  98
  99         <varlistentry>
 100             <term>filterParams (optional)</term>
 101
 102             <listitem>
 103                 <para>
 104                     An associative array of parameters to use when instantiating the log filter.
 105                     Each log filter's <methodname>factory()</methodname> method will map these to
 106                     constructor arguments, as noted below.
 107                 </para>
 108             </listitem>
 109         </varlistentry>
 110
 111         <varlistentry>
 112             <term>filterNamespace (optional)</term>
 113
 114             <listitem>
 115                 <para>
 116                     The class prefix/namespace to use when constructing the final log filter
 117                     classname. By default, if this is not provided, "Zend_Log_Filter" is assumed;
 118                     however, you can pass your own namespace if you are using a custom log filter.
 119                 </para>
 120             </listitem>
 121         </varlistentry>
 122     </variablelist>
 123
 124     <para>
 125         Each writer and each filter has specific options.
 126     </para>
 127
 128     <sect2 id="zend.log.factory.writer-options">
 129         <title>Writer Options</title>
 130
 131         <sect3 id="zend.log.factory.writer-options.db">
 132             <title>Zend_Log_Writer_Db Options</title>
 133
 134             <variablelist>
 135                 <varlistentry>
 136                     <term>db</term>
 137
 138                     <listitem>
 139                         <para>
 140                             A <classname>Zend_Db_Adapter</classname> instance.
 141                         </para>
 142                     </listitem>
 143                 </varlistentry>
 144
 145                 <varlistentry>
 146                     <term>table</term>
 147
 148                     <listitem>
 149                         <para>
 150                             The name of the table in the RDBMS that will contain log entries.
 151                         </para>
 152                     </listitem>
 153                 </varlistentry>
 154
 155                 <varlistentry>
 156                     <term>columnMap</term>
 157
 158                     <listitem>
 159                         <para>
 160                             An associative array mapping database table column names to log event
 161                             fields.
 162                         </para>
 163                     </listitem>
 164                 </varlistentry>
 165             </variablelist>
 166         </sect3>
 167
 168         <sect3 id="zend.log.factory.writer-options.firebug">
 169             <title>Zend_Log_Writer_Firebug Options</title>
 170
 171             <para>
 172                 This log writer takes no options; any provided will be ignored.
 173             </para>
 174         </sect3>
 175
 176         <sect3 id="zend.log.factory.writer-options.mail">
 177             <title>Zend_Log_Writer_Mail Options</title>
 178
 179             <para>
 180                 <classname>Zend_Log_Writer_Mail</classname> currently (as of 1.10) does not
 181                 implement a factory, and will raise an exception if you attempt to instantiate it
 182                 via <methodname>Zend_Log::factory()</methodname>.
 183             </para>
 184         </sect3>
 185
 186         <sect3 id="zend.log.factory.writer-options.mock">
 187             <title>Zend_Log_Writer_Mock Options</title>
 188
 189             <para>
 190                 This log writer takes no options; any provided will be ignored.
 191             </para>
 192         </sect3>
 193
 194         <sect3 id="zend.log.factory.writer-options.null">
 195             <title>Zend_Log_Writer_Null Options</title>
 196
 197             <para>
 198                 This log writer takes no options; any provided will be ignored.
 199             </para>
 200         </sect3>
 201
 202         <sect3 id="zend.log.factory.writer-options.stream">
 203             <title>Zend_Log_Writer_Stream Options</title>
 204
 205             <variablelist>
 206                 <varlistentry>
 207                     <term>stream|url</term>
 208
 209                     <listitem>
 210                         <para>
 211                             A valid <acronym>PHP</acronym> stream identifier to which to log.
 212                         </para>
 213                     </listitem>
 214                 </varlistentry>
 215
 216                 <varlistentry>
 217                     <term>mode</term>
 218
 219                     <listitem>
 220                         <para>
 221                             The I/O mode with which to log; defaults to "a", for "append".
 222                         </para>
 223                     </listitem>
 224                 </varlistentry>
 225             </variablelist>
 226         </sect3>
 227
 228         <sect3 id="zend.log.factory.writer-options.syslog">
 229             <title>Zend_Log_Writer_Syslog Options</title>
 230
 231             <variablelist>
 232                 <varlistentry>
 233                     <term>application</term>
 234
 235                     <listitem>
 236                         <para>
 237                             Application name used by the syslog writer.
 238                         </para>
 239                     </listitem>
 240                 </varlistentry>
 241
 242                 <varlistentry>
 243                     <term>facility</term>
 244
 245                     <listitem>
 246                         <para>
 247                             Facility used by the syslog writer.
 248                         </para>
 249                     </listitem>
 250                 </varlistentry>
 251             </variablelist>
 252         </sect3>
 253
 254         <sect3 id="zend.log.factory.writer-options.zendmonitor">
 255             <title>Zend_Log_Writer_ZendMonitor Options</title>
 256
 257             <para>
 258                 This log writer takes no options; any provided will be ignored.
 259             </para>
 260         </sect3>
 261     </sect2>
 262
 263     <sect2 id="zend.log.factory.filter-options">
 264         <title>Filter Options</title>
 265
 266         <sect3 id="zend.log.factory.filter-options.message">
 267             <title>Zend_Log_Filter_Message Options</title>
 268
 269             <variablelist>
 270                 <varlistentry>
 271                     <term>regexp</term>
 272
 273                     <listitem>
 274                         <para>
 275                             Regular expression that must be matched in order to log a message.
 276                         </para>
 277                     </listitem>
 278                 </varlistentry>
 279             </variablelist>
 280         </sect3>
 281
 282         <sect3 id="zend.log.factory.filter-options.priority">
 283             <title>Zend_Log_Filter_Priority Options</title>
 284
 285             <variablelist>
 286                 <varlistentry>
 287                     <term>priority</term>
 288
 289                     <listitem>
 290                         <para>
 291                             The maximum priority level by which messages will be logged.
 292                         </para>
 293                     </listitem>
 294                 </varlistentry>
 295
 296                 <varlistentry>
 297                     <term>operator</term>
 298
 299                     <listitem>
 300                         <para>
 301                             The comparison operator by which to do priority comparisons; defaults to
 302                             "&lt;=".
 303                         </para>
 304                     </listitem>
 305                 </varlistentry>
 306             </variablelist>
 307         </sect3>
 308
 309         <sect3 id="zend.log.factory.filter-options.suppress">
 310             <title>Zend_Log_Writer_Suppress Options</title>
 311
 312             <para>
 313                 This log filter takes no options; any provided will be ignored.
 314             </para>
 315         </sect3>
 316     </sect2>
 317
 318     <sect2 id="zend.log.factory.custom">
 319         <title>Creating Configurable Writers and Filters</title>
 320
 321         <para>
 322             If you find yourself needing to write your own log writers and/or filters, you can make
 323             them compatible with <methodname>Zend_Log::factory()</methodname> very easily.
 324         </para>
 325
 326         <para>
 327             At the minimum, you need to implement
 328             <interfacename>Zend_Log_FactoryInterface</interfacename>, which expects a static
 329             <methodname>factory()</methodname> method that accepts a single argument,
 330             <varname>$config</varname>, which may be either an array or
 331             <classname>Zend_Config</classname> object. If your log writer extends
 332             <classname>Zend_Log_Writer_Abstract</classname>, or your log filter extends
 333             <classname>Zend_Log_Filter_Abstract</classname>, you will pick this up for free.
 334         </para>
 335
 336         <para>
 337             Then, simply define mappings between the accepted configuration and any constructor
 338             arguments. As an example:
 339         </para>
 340
 341         <programlisting language="php"><![CDATA[
 342 class My_Log_Writer_Foo extends Zend_Log_Writer_Abstract
 343 {
 344     public function __construct($bar, $baz)
 345     {
 346         // ...
 347     }
 348
 349     public static function factory($config)
 350     {
 351         if ($config instanceof Zend_Config) {
 352             $config = $config->toArray();
 353         }
 354         if (!is_array($config)) {
 355             throw new Exception(
 356                 'factory expects an array or Zend_Config instance'
 357             );
 358         }
 359
 360         $default = array(
 361             'bar' => null,
 362             'baz' => null,
 363         );
 364         $config = array_merge($default, $config);
 365
 366         return new self(
 367             $config['bar'],
 368             $config['baz']
 369         );
 370     }
 371 }
 372 ]]></programlisting>
 373
 374         <para>
 375             Alternately, you could call appropriate setters after instantiation, but prior to
 376             returning the instance:
 377         </para>
 378
 379         <programlisting language="php"><![CDATA[
 380 class My_Log_Writer_Foo extends Zend_Log_Writer_Abstract
 381 {
 382     public function __construct($bar = null, $baz = null)
 383     {
 384         // ...
 385     }
 386
 387     public function setBar($value)
 388     {
 389         // ...
 390     }
 391
 392     public function setBaz($value)
 393     {
 394         // ...
 395     }
 396
 397     public static function factory($config)
 398     {
 399         if ($config instanceof Zend_Config) {
 400             $config = $config->toArray();
 401         }
 402         if (!is_array($config)) {
 403             throw new Exception(
 404                 'factory expects an array or Zend_Config instance'
 405             );
 406         }
 407
 408         $writer = new self();
 409         if (isset($config['bar'])) {
 410             $writer->setBar($config['bar']);
 411         }
 412         if (isset($config['baz'])) {
 413             $writer->setBaz($config['baz']);
 414         }
 415         return $writer;
 416     }
 417 }
 418 ]]></programlisting>
 419     </sect2>
 420 </sect1>