4113 - trunk/EventLog/docs [eZComponents: Trunk]

Author: Alexandru Stanoi
Date: 2006-11-28 15:15:57 +0100 (Tue, 28 Nov 2006)
New Revision: 4113

Log:
- Removed the database example from the tutorial, as it has been moved to
  EventLogDatabaseTieIn.

Removed:
   trunk/EventLog/docs/tutorial_database.php
Modified:
   trunk/EventLog/docs/tutorial.txt

Modified: trunk/EventLog/docs/tutorial.txt
===================================================================
--- trunk/EventLog/docs/tutorial.txt    2006-11-28 14:10:30 UTC (rev 4112)
+++ trunk/EventLog/docs/tutorial.txt    2006-11-28 14:15:57 UTC (rev 4113)
@@ -13,17 +13,18 @@
 
 The available log writers are:
 
-- ezcLogDatabaseWriter, which writes log messages to the database.
-- ezcLogUnixFileWriter, which writes log messages to a file in an 'Unix' file 
+- ezcLogUnixFileWriter, which writes log messages to a file in an 'Unix' file
   format.
+- ezcLogDatabaseWriter, which writes log messages to the database. Available
+  in the EventLogDatabaseTieIn_ component.
 
-Each of these writers can be customized or extended. 
+Each of these writers can be customized or extended.
 
 An incoming log message can be written to zero or more writers. The writers
 that write the log message depends on the variables of the log message itself 
and the
 ezcLogMapper implementation. An implementation of the ezcLogMapper checks the
-severity, source, and category from the log message and forwards the message 
-to the matching writers. 
+severity, source, and category from the log message and forwards the message
+to the matching writers.
 
 
 Class overview
@@ -32,55 +33,51 @@
 The following classes are most important to use, customize, or extend:
 
 ezcLog
-  The ezcLog is a singleton, meaning that only one instance to the log can 
+  The ezcLog is a singleton, meaning that only one instance to the log can
   exist. This class provides methods to configure and record log messages. The
   recorded log messages are sent to an implementation of the ezcLogMapper,
-  deciding which writers should write the log message. 
+  deciding which writers should write the log message.
 
 ezcLogMapper
   The ezcLogMapper provides an interface for the log message mapping. Log
   messages are dispatched from the ezcLog to a writer. To which writer a
   message is dispatched is determined in the class that implements
-  ezclogMapper and is assigned in the ezcLog.  
+  ezclogMapper and is assigned in the ezcLog.
 
 ezcLogFilterSet
   The ezcLogFilterSet is an implementation of the ezcLogMapper. The
   ezcLogFilterSet contains a set of ezcLogFilterRules. These rules are
-  processed sequentially. The rule assigned first will be processed first.  
+  processed sequentially. The rule assigned first will be processed first.
   Each rule determines whether the log message matches with the filter rule. 
If the
   log message matches, it calls the writer and decide whether the filter set
   stops processing.
 
-  The ezclogFilterSet is inspired by modern mail applications regarding the
+  The ezcLogFilterSet is inspired by modern mail applications regarding the
   mail filter settings. Normally these mail filter settings sort the incoming
-  mail and stores it in the correct mail folder.  
+  mail and stores it in the correct mail folder.
 
 ezcLogWriter
   The ezcLogWriter provides an interface for the writers. An implementation
-  of this interface is a valid writer, and can be addressed by the 
ezcLogMapper. 
+  of this interface is a valid writer, and can be addressed by the 
ezcLogMapper.
   The writer itself can determine how and where the log message is stored.
 
 ezcLogUnixFileWriter
-  The ezcLogUnixFileWriter writes the log message to a file. 
+  The ezcLogUnixFileWriter writes the log message to a file.
 
-ezcLogDatabaseWriter
-  The ezcLogDatabaseWriter writes the log message to a database.
-
 ezcLogFilter
   The ezcLogFilter is a structure to specify which log messages are accepted in
   a filter set.
-  
- 
+
 For more information about these classes, see the class documentation.
 
 
 Examples
 ========
 
-Writing a log message to a file.
---------------------------------
+Writing a log message to a file
+-------------------------------
 
-This example creates a file writer, and assigns it to the default log mapper. 
+This example creates a file writer, and assigns it to the default log mapper.
 
 .. include:: tutorial_simple_file_writer.php
    :literal:
@@ -89,52 +86,52 @@
 correct php files for the EventLog component.
 
 Hereafter the log is set up, and a message is written to the log file
-"default.log" and the file will be placed in the "/tmp/log" directory.
+"default.log" and the file will be placed in the "/tmp/logs" directory.
 
-After execution, the file "/tmp/log/default.php" contains something like::
+After execution, the file "/tmp/logs/default.log" contains something like::
 
-    Jan 24 14:39:57 [Warning] [default] [default] Could not connect with the 
payment server. 
+    Jan 24 14:39:57 [Warning] [default] [default] Could not connect with the 
payment server.
 
 Respectively the date, severity, source, category, and message are shown. The
 source and category are both set to default, because they were not specified in
-the message. 
+the message.
 
 
 Assigning sources and categories
 --------------------------------
 
-The default source and category from the ezcLog can be set via the properties:
+The default source and category from the ezcLog can be set via the properties
 "source" and "category". The next example demonstrates how the default
 properties can be set and how extra variables can be added to the log.
 
 .. include:: tutorial_sources_categories.php
    :literal:
 
-After execution, the file "/tmp/log/default.php" contains something like::
+After execution, the file "/tmp/logs/default.log" contains something like::
 
-    Jan 24 15:45:04 [Warning] [Payment module] [Template] Could not find cache 
file: </var/cache/payment1234.cache>. 
-    Jan 24 15:45:04 [Error] [Payment module] [SQL] Cannot execute query: 
<SELECT * FROM Orders WHERE ID = '123'>. 
+    Jan 24 15:45:04 [Warning] [Payment module] [Template] Could not find cache 
file: </var/cache/payment1234.cache>.
+    Jan 24 15:45:04 [Error] [Payment module] [SQL] Cannot execute query: 
<SELECT * FROM Orders WHERE ID = '123'>.
     Jan 24 15:45:04 [Debug] [Payment module] Starting shutdown process. (file: 
/home/rb/php5/ezcomponents/packages/EventLog/trunk/docs/tutorial_sources_categories.php,
 line: 25)
 
 
 Adding log attributes automatically
 -----------------------------------
 
-Some cases it is convenient to add automatically log attributes to the log
-message. For example: 
+In some cases it is convenient to add automatically log attributes to the log
+message. For example:
 
-- Audit trails should include the current user. 
-- A payment system should always include the order number. 
+- Audit trails should include the current user.
+- A payment system should always include the order number.
 
 However, the log attributes appended to the log message are static. The
-value assigned to the attribute will be the same. 
+value assigned to the attribute will be the same.
 
 The next example assigns two automatic attributes:
 
 .. include:: tutorial_auto_variables.php
    :literal:
 
-After execution, the file "/tmp/log/default.php" contains::
+After execution, the file "/tmp/logs/default.log" contains::
 
     Jan 25 10:15:19 [Failed audit] [security] [login/logoff] Authentication 
failed (username: John Doe)
     Jan 25 10:15:19 [Debug] [Payment] [external connections] Connecting with 
the server. (service: Paynet Terminal)
@@ -148,7 +145,7 @@
 writers. This example handles the log message as follows:
 
 - Ignore all message with the severity DEBUG.
-- Store the audit trails in the "audit.log" file. 
+- Store the audit trails in the "audit_trails.log" file.
 - Store the logs with the Payment category in the "payment.log" file.
 - Store all the messages, except DEBUG, in the "general.log" file.
 
@@ -158,48 +155,21 @@
    :literal:
 
 
-
-Writing to the MySQL database
------------------------------
-
-To write log messages to the database, the Database component is used. The
-table to which the log is written should already exist.
-
-.. include:: tutorial_database.php
-   :literal:
-
-The database: "logs" and the table "general" should exist. The table should at
-least contain the columns: time, message, severity, source, category. An
-example MySQL query to create the table::
-
-  CREATE TABLE `general` 
-  ( 
-       `id` INT NOT NULL AUTO_INCREMENT, 
-       `time` DATETIME NOT NULL,
-       `message` VARCHAR( 255 ) NOT NULL, 
-       `severity` VARCHAR( 40 ) NOT NULL, 
-       `source` VARCHAR( 100 ) NOT NULL ,
-       `category` VARCHAR( 100 ) NOT NULL, 
-       `file` VARCHAR( 100 ) NOT NULL, 
-       `line` INT NOT NULL, 
-       PRIMARY KEY ( `id` )
-  )
-
-
 Using trigger_error()
 ---------------------
 
 The EventLog component is designed that it can be used with trigger_error_ or
 stand-alone. Instead of calling the ezcLog::getInstance()->log() method, the
-trigger_error can be called.  Using the trigger_error method makes your code
+trigger_error() can be called.  Using the trigger_error() method makes your 
code
 less Log package dependent and produces less overhead when logging is disabled.
- 
+
 The function set_error_handler_ should set up a callback function (or method)
 that in its turn calls the EventLog. See for more information the
 ezcLog::logHandler() method.
 
 .. _trigger_error: http://www.php.net/trigger_error
 .. _set_error_handler: http://www.php.net/set_error_handler
+.. _EventLogDatabaseTieIn: 
http://ez.no/doc/components/view/trunk/(file)/introduction_EventLogDatabaseTiein.html
 
 
 

Deleted: trunk/EventLog/docs/tutorial_database.php
===================================================================
--- trunk/EventLog/docs/tutorial_database.php   2006-11-28 14:10:30 UTC (rev 
4112)
+++ trunk/EventLog/docs/tutorial_database.php   2006-11-28 14:15:57 UTC (rev 
4113)
@@ -1,21 +0,0 @@
-<?php
-
-require_once 'tutorial_autoload.php';
-date_default_timezone_set( "UTC" );
-
-// Open database connection.
-$db = ezcDbFactory::create( "mysql://root@localhost/logs" );
-
-// Create the database writer.
-// Attach to the database handler. And write log entries to the table: 
"default".
-$writer = new ezcLogDatabaseWriter( $db, "general" );
-
-$log = ezcLog::getInstance();
-
-// Write everything to the database.
-$log->getmapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, 
$writer, true ) );
-
-// Write a message
-$log->log( "Cannot load Payment module", ezcLog::ERROR, array( "source" => 
"shop", "category" => "modules" ) );
-
-?>