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 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:

 <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)

 <log>
  <type>display</type>
  <level>6</level> <!-- PEAR_LOG_INFO -->
 </log>

Example 2: Using 'syslog' container

 <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

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

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

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 Full-Query Logging HOWTO for information about how to configure this query logging.