= Configure Logging =

In this guide we'll look at how to set up logging for Propel.  Propel uses the configured logging facility to record errors (all serious errors are also thrown as ''!PropelException''), warnings, and debug information.

The built-in logging is configured in the runtime configuration file, {{{runtime-conf.xml}}}.  If you're unsure about what this is or where to find it, you should probably stop and read the [wiki:Users/Documentation/1.3/QuickStart Quickstart Guide] first.

By default Propel will attempt to use the Log framework that is distributed with PEAR; however, it is also easy to configure Propel to use your own logging framework -- or none at all.

== Configuring Default (PEAR) Logging ==

The default logging is configured in the ''<log>'' section of your project's {{{runtime-conf.xml}}} file.  Here is the accepted format for this section with the default values that Propel uses:

{{{
#!xml
 <log>
  <type>file</type>
  <name>./propel.log</name>
  <ident>propel</ident>
  <level>7</level> <!-- PEAR_LOG_DEBUG -->
  <conf></conf>
 </log>
}}}

Note that the ''<level>'' needs to correspond to the integer represented by the ''PEAR_LOG_*'' constants.

||'''Constant'''||'''Value'''||
||PEAR_LOG_EMERG||0||
||PEAR_LOG_ALERT||1||
||PEAR_LOG_CRIT||2||
||PEAR_LOG_ERR||3||
||PEAR_LOG_WARNING||4||
||PEAR_LOG_NOTICE||5||
||PEAR_LOG_INFO||6||
||PEAR_LOG_DEBUG||7||


The meaning of each of the nested elements may vary, depending on which Log container you are using.  Also, for many of the Log containers, not all of these parameters are required.

Here are a few more examples:

'''Example 1:''' Using 'display' container (for output to HTML)
{{{
#!xml
 <log>
  <type>display</type>
  <level>6</level> <!-- PEAR_LOG_INFO -->
 </log>
}}}

'''Example 2:''' Using 'syslog' container
{{{
#!xml
 <log>
  <type>syslog</type>
  <name>8</name> <!-- LOG_USER -->
  <ident>propel</ident>
  <level>6</level>
 </log>
}}}


== Configuring Custom Logging ==

In many cases you may wish to integrate Propel's logging facility with the rest of your web application.  If you omit the ''<log>'' section of your {{{runtime-conf.xml}}} then Propel will not setup *any* logging for you.  In this case, you should set a logging facility for Propel if you want it to log messages.  


=== Setting Your Own PEAR Logger ===

Here's an example of how you could configure your own PEAR logger and then set Propel to use this for logging.

{{{
#!php
<?php

require_once 'Log.php';
$logger = Log::factory('syslog', LOG_LOCAL0, 'propel', array(), PEAR_LOG_INFO);

require_once 'propel/Propel.php';

Propel::setLogger($logger);
Propel::init('/path/to/runtime-conf.php');
}}}

=== Using Non-PEAR Logger ===

There is a ''!BasicLogger'' interface provided with Propel runtime that specifies the interface that your log container must implement in order to be compatible with Propel.  You do not actually have to implement the interface, but all the specified methods must be present in your container.

There is also a bundled ''!MojaviLogAdapter'' class which allows you to use a Mojavi logger with Propel.

Here's an example a simple log container suitable for use with Propel:

{{{
#!php
<?php

class MyLogger {

  public function emergency($m) {
    $this->log($m, Propel::LOG_EMERG);
  } 

  public function alert($m) {
    $this->log($m, Propel::LOG_ALERT);
  }
  
  public function crit($m) {
    $this->log($m, Propel::LOG_CRIT);
  }
  
  public function err($m) {
    $this->log($m, Propel::LOG_ERR);
  }

  public function warning($m) {
    $this->log($m, Propel::LOG_WARNING);
  }

  public function notice($m) {
    $this->log($m, Propel::LOG_NOTICE);
  }

  public function info($m) {
    $this->log($m, Propel::LOG_INFO);
  }

  public function debug($m) {
    $this->log($m, Propel::LOG_DEBUG);
  }

  public function log($m, $priority) {
    $this->display($m, $this->priorityToColor($priority));
  }
  
  private function display($message, $color) {
    echo "<p style='color: $color'>$message</p>";
  }

  private function priorityToColor($priority) {
     switch($priority) {
       case Propel::LOG_EMERG:
       case Propel::LOG_ALERT:
       case Propel::LOG_CRIT:
       case Propel::LOG_ERR:
         return 'red';
         break;       
       case Propel::LOG_WARNING:
         return 'orange';
         break;
       case Propel::LOG_NOTICE:
         return 'green';
         break;
       case Propel::LOG_INFO:
         return 'blue';
         break;
       case Propel::LOG_DEBUG:
         return 'grey';
         break;
     }
  }
}

?>
}}}

... which can be easily hooked into Propel:

{{{
#!php
<?php

require_once 'MyLogger.php';

$logger = new MyLogger();

require_once 'propel/Propel.php';

Propel::setLogger($logger);
Propel::init('/path/to/runtime-conf.php');
}}}

== Full-Query Logging ==

The logger that you configure Propel to use can also be used to log queries and bind parameter values.  See the [wiki:Users/Documentation/1.3/HowTos/FullQueryLogging Full-Query Logging HOWTO] for information about how to configure this query logging.