Author: Frederik Holljen Date: 2005-12-12 20:21:17 +0100 (Mon, 12 Dec 2005) New Revision: 1343
Log: Review and doc update Added: packages/EventLog/trunk/review.txt Modified: packages/EventLog/trunk/src/context.php packages/EventLog/trunk/src/exceptions/file_exception.php packages/EventLog/trunk/src/exceptions/writer_exception.php packages/EventLog/trunk/src/interfaces/writer.php packages/EventLog/trunk/src/log.php packages/EventLog/trunk/src/log_message.php packages/EventLog/trunk/src/map.php packages/EventLog/trunk/src/writers/writer_database.php packages/EventLog/trunk/src/writers/writer_file.php packages/EventLog/trunk/src/writers/writer_unix_file.php Added: packages/EventLog/trunk/review.txt =================================================================== --- packages/EventLog/trunk/review.txt 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/review.txt 2005-12-12 19:21:17 UTC (rev 1343) @@ -0,0 +1,38 @@ +Review Frederik +=============== +ezcLogFilter - This is a struct. Place into structs directory and add constructur and the __ method. + +ezcLog - Add large example on how to use the class a a logger. +ezcLog::attach/detach - These names are strange as we are not attaching anything. What about: map and unmap? +ezcLog::setSeverityAttributes/setSourceAttributes - These need doc tag cleanup and examples in order to be understandable. Maybe a rename of the methods would be nice also. E.g setStandardSeverityAttributes +ezcLog::LogHandler - name starts with capital letter? Add example on how to use trigger_error. +ezcLog::__set and __get don't throw when they should. + +ezcLogWriter::writeLogMessage - source and category, where do these come from? + +ezcLogContext - Class description needs a better introduction an example. + +ezcLogMap - rename to ezcWriterMap? Or are we using it for other things as well? +ezcLogMap - The intro from "Our solution" is a bit unclear to me. +ezcLogMap::map --> addMap? (remove ambiguity) +ezcLogMap::mergeSingle - lacks doc. I'm not entirely sure what this method does. .. $tmp?? +ezcLogMap::mergeHash - lacks doc and is marked for rewriting. +ezcLogMap::unmergeHash - lacks doc and is marked for rewriting. +ezcLogMap::printStructure - lacks doc +ezcLogMap::printStructureRecursive - lacks doc + +ezcLogFileException - constants. Correct naming? (capital vs non capital?) + +ezcLogMessage::__set and __get does not throw when they should +ezcLogMessage::parseMessage - document the format for $message. + +ezcLogWriterDatabase - Document the properties and how they work with the table that is writes to. +ezcLogWriterDatabase::__construct - doc talks about tie-in. What do you mean by that in this context? +ezcLogWriterBase:: last three methods. Should they be public? They also lack doc. +ezcLogWriterBase::writeLogEntry - only doc no impl. Should this be removed? + +ezcLogWriterBase::rotateLog - shouldn't the for loop start at ($this->maxFiles - 1)? + +ezcLogWriterBase::logTo - you do not catch the exception from openFile, should it be catched and rethrown or should it be documented? +ezcLogWriterBase::logTo -> mapEventToFile ? +ezcLogWriterBase::logNotTo ->unmapEventToFile \ No newline at end of file Property changes on: packages/EventLog/trunk/review.txt ___________________________________________________________________ Name: svn:eol-style + native Modified: packages/EventLog/trunk/src/context.php =================================================================== --- packages/EventLog/trunk/src/context.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/context.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -6,6 +6,7 @@ * @version //autogentag// * @copyright Copyright (C) 2005 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License + * @access private */ /** @@ -13,23 +14,30 @@ * * @package EventLog * @version //autogentag// + * @access private */ class ezcLogContext { /** - * @var array( integer => array ) Stores the contexts for the severities. + * Stores the contexts for the severities. + * + * @var array(integer=>array) */ protected $severityMap; /** - * @var array( string => array ) Stores the contexts for the sources. + * Stores the contexts for the sources. + * + * @var array(string=>array) */ protected $sourceMap; /** - * Delete all contexts. + * Resets this object to its initial state by removing all context mappings. + * + * @return void */ public function reset() { @@ -38,17 +46,18 @@ } /** - * Set a context for a given group of severities. + * Set the context $context for the sevirities specified by $severityMask. + * * If the severity already exist, the value will update the old value with * the new one. * + * $context is of the format array('key'=>'value'). + * * @param int $severityMask * Bitmask that specifies all the event types that share the given * context. - * - * @param array(string => string) $context - * Specifies the keys and values that should be stored into this - * context object. + * @param array(string=>string) $context + * @return void */ public function setSeverityContext( $severityMask, $context ) { @@ -71,11 +80,13 @@ } /** - * Remove the contexts for the given eventTypes. + * Remove the contexts for the severities given by $severityMask. * + * $severityMask is a bitmask that specifies all the event types that should remove + * their context. + * * @param int $severityMask - * Bitmask that specifies all the event types that should remove - * their context. + * @return void */ public function unsetSeverityContext( $severityMask ) { @@ -93,19 +104,19 @@ } /** - * Add a context for each eventSource specified by the $eventSources - * array. If a certain key from the given context does already exist, the + * Set the context $context for each eventSource specified by $eventSources. + * + * If a certain key from the given context does already exist, the * new value will replace the value stored in the context itself. (Value is * updated). * * @param array(string) $eventSources - * Event sources that share the given context. - * - * @param array(string => string) $context + * @param array(string=>string) $context * Specifies the keys and values that should be stored into this * context object. + * @return void */ - public function setSourceContext( $eventSources, $context ) + public function setSourceContext( array $eventSources, $context ) { foreach ( $eventSources as $eventSource ) { @@ -119,12 +130,12 @@ } /** - * Remove the contexts for the given eventSources. + * Remove the contexts for the given $eventSources. * * @param array(string) $eventSources - * All the event types that should remove their context. + * @return void */ - public function unsetSourceContext( $eventSources ) + public function unsetSourceContext( array $eventSources ) { foreach ( $eventSources as $eventSource ) { @@ -133,17 +144,16 @@ } /** - * Returns the complete context for the given event type and event source. + * Returns the complete context for the event type $eventType and event source $eventSource. + * * If there is no context available this method will return an empty array. * * * @param integer $eventType The integer that specifies the event type. * The range of this integer is 2^(N+): * ( 1, 2, 4, 8, ... ) - * @param string $eventSource The string that specifies the event source. - * - * @return boolean The value true if the context is correct, otherwise - * false. + * @param string $eventSource + * @return array */ public function getContext( $eventType, $eventSource ) { Modified: packages/EventLog/trunk/src/exceptions/file_exception.php =================================================================== --- packages/EventLog/trunk/src/exceptions/file_exception.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/exceptions/file_exception.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -1,13 +1,15 @@ <?php /** - * File containing the ezcFileWriterException class - * + * File containing the ezcFileWriterException class. + * * @package EventLog * @version //autogen// * @copyright Copyright (C) 2005 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License */ /** + * Exception thrown when a file input/output error occures. + * * @package EventLog * @version //autogen// */ @@ -23,13 +25,14 @@ const CannotWrite = 4; /** + * Constructs a new ezcLogFileExcpetion with the message $message and the error code $code. * + * @param string $message * @param int $code */ public function __construct( $message, $code ) { parent::__construct( $message, $code ); } - } ?> Modified: packages/EventLog/trunk/src/exceptions/writer_exception.php =================================================================== --- packages/EventLog/trunk/src/exceptions/writer_exception.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/exceptions/writer_exception.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -1,19 +1,22 @@ <?php /** - * File containing the ezcLogWriterException class - * + * File containing the ezcLogWriterException class. + * * @package EventLog * @version //autogen// * @copyright Copyright (C) 2005 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License */ /** + * Exception thrown when a writer encounters an error. + * * @package EventLog * @version //autogen// */ class ezcLogWriterException extends Exception { /** + * Constructs a new ezcLogWriterExcpetion with the message $message. * * @param int $code */ Modified: packages/EventLog/trunk/src/interfaces/writer.php =================================================================== --- packages/EventLog/trunk/src/interfaces/writer.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/interfaces/writer.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -9,8 +9,8 @@ */ /** - * Interface that defines a log writer. Every class that implements the - * interface can be used as a log writer. + * ezcLogWriter defines the common interface for all classes that implements + * writing of a log message. * * @package EventLog * @version //autogentag// @@ -18,32 +18,25 @@ interface ezcLogWriter { /** - * Writes a log message to the log writer. + * Writes the message $message to the log. * * The writer can use the severity, source, and category to filter the * incoming messages and determine the location where the messages should * be written. * - * @param string message - * The message that should be written. + * $optional may contain extra information that can be added to the log. For example: + * line numbers, file names, usernames, etc. * + * @param string message * @param int severity - * The severity or type of the message. These numbers can be - * resolved by the ezcLog::getSeverityName() method. + * ezcLog:: DEBUG, SUCCES_AUDIT, FAIL_AUDIT, INFO, NOTICE, WARNING, ERROR or FATAL. * + * @throws ezcLogWriterException when the log writer was unable to write + * the log message. * $param string source - * The source of the message. - * * @param string category - * The category of the message. - * * @param array(string=>string) optional - * Extra information that can be added to the log. For example: - * line numbers, file names, usernames, etc. - * - * - * @throws ezcLogWriterException when the log writer was unable to write - * the log message. + * @return void */ public function writeLogMessage( $message, $severity, $source, $category, $optional = array() ); } Modified: packages/EventLog/trunk/src/log.php =================================================================== --- packages/EventLog/trunk/src/log.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/log.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -22,7 +22,7 @@ * * The category defines the group of the message. In log messages it can be: * sql, template, etc. For audit trails can it be used as: edit, published, - * login/logout, ec. + * login/logout, etc. * * * @package EventLog @@ -42,40 +42,46 @@ const ERROR = 64; const FATAL = 128; - /** - * @var array - * An array that contains the properties of this object. + * Holds the properties of this class. + * + * @var array(string=>mixed) */ private $properties = array(); - /** + * Contains the mapping between the log messages and the writers. + * * @var ezcLogMap - * Contains the mapping between the log messages and the writers. */ protected $writers; /** + * Stores the context of the eventType and eventSources + * * $var ezcLogContext - * Stores the context of the eventType and eventSources */ protected $context; /** + * Store the instance of this class. + * * @var Log - * Store the instance of this class. */ private static $instance = null; /** + * Stores the setting whether writer exceptions should be thrown. + * * @var boolean - * Stores the setting whether writer exceptions should be thrown. */ private $throwWriterExceptions = true; /** - * Use the getInstance() method instead to get the a Log instance. + * Constructs an empty ezcLog instance. + * + * This constructor is private as this class should be used as a + * singleton. Use the getInstance() method instead to get the Log instance. */ private function __construct() { @@ -85,7 +91,7 @@ /** * Returns the instance of the class. * - * @returns Instance of the class. + * @return Instance of the class. */ public static function getInstance() { @@ -97,7 +103,12 @@ } /** - * Property set + * Sets the property $name to $value. + * + * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @param string $name + * @param mixed $value + * @return void */ public function __set( $name, $value ) { @@ -108,8 +119,12 @@ } } - /** - * Property get + /** + * Returns the property $name. + * + * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @param string $name + * @return mixed */ public function __get( $name ) { @@ -121,9 +136,12 @@ } /** - * Resets the log instance. All sourceAttributes, severityAttributes, and - * writers will be removed. The default source and category are set to - * their default values. + * Resets the log instance to its initial state. + * + * All sourceAttributes, severityAttributes, and writers will be removed. + * The default source and category are set to their default values. + * + * @return void */ public function reset() { @@ -135,9 +153,10 @@ /** * Sets the default logging values. + * * The initial values from the source and category are set to "default". * - * This method is called by the constructor and the reset method. + * @return void */ protected function setDefaults() { @@ -147,16 +166,15 @@ /** * Enable or disable writer exceptions to be thrown when an log entry - * couldn't be written to a writer. + * could not be written. * - * On one hand the intention of the application developer will be to enable - * exceptions whenever an log message can not be written. This yields - * especially in the development phase. On the other hand, a live server - * should not throw a 'deadly' exception when a relatively unimportant - * notice can not be written to the log. + * Typically you want to have exceptions on while developing your application + * in order to catch potential problems. A live server however, should not throw + * a fatal exception when a relatively uninmport notice could not be written to + * the log. For these setups you can turn the exceptions off. * - * @param boolean @enable True means that the exceptions are enabled, - * whereas false indicates that the exceptions are disabled. + * @param boolean + * @return void */ public function throwWriterExceptions( $enable ) { @@ -164,15 +182,16 @@ } /** - * Write a message to the log writers. The writer that will be used, - * depends on the severity, source, and category. The severity is the - * second parameter. The source and category can (is optional) be defined - * in the attributes array. If these are omitted, then the default values - * will be assigned. + * Write the message $message to the log. + * + * The message will be dispatched to one of the writers. The writer that will + * be used, depends on the $severity, source, and category. The source and category + * can (optionally) be defined the attributes array. If these are omitted, then the default + * values will be used. * + * @throws ezcLogWriterException when exception are enabled in the Log + * class and something went wrong while writing the log entry. * @param string message - * Log message that should be written. - * * @param int severity * The eventType which should be one of the following constants: * DEBUG, SUCCES_AUDIT, FAIL_AUDIT, INFO, NOTICE, WARNING, ERROR, FATAL. @@ -187,10 +206,7 @@ * ( .., "file" => __FILE__, "line" => __LINE__, .. ) * </code> * - * - * @throws ezcLogWriterException when exception are enabled in the Log - * class and something went wrong while writing the log entry. - * + * @return void */ public function log( $message, $severity, array $attributes = array() ) { @@ -218,16 +234,15 @@ } /** - * Attaches a writer to a group of incoming messages. The group of - * messages is specified with an ezcLogFilter object. + * Set the writer $writer to log messages of the type specified by + * $logFilter. + * + * Whenever a messages that matches the attributes of $logFilter it will + * be written by $writer. * * @param ezcLogFilter $logFilter - * This structure defines the messages that should be sent to the - * specified writer. - * * @param ezcLogWriter $writer - * The writer that will handle the log messages, if it matches the logFilter. - * + * @return void */ public function attach( ezcLogFilter $logFilter, ezcLogWriter $writer ) { @@ -235,16 +250,12 @@ } /** - * Detaches a writer from a group of incoming messages. The group of - * messages that should be detached is specified in the ezcLogFilter object. + * Detaches the writer $writer from messages of the type specified by + * $logFilter. * * @param ezcLogFilter $logFilter - * This structure defines the messages that should be sent to the - * specified writer. - * * @param ezcLogWriter $writer - * The writer that should be detached. - * + * @return void */ public function detach( ezcLogFilter $logFilter, ezcLogWriter $writer ) { @@ -261,6 +272,7 @@ * * @param array(string => string) $attributes * Array with context strings. + * @return void */ public function setSeverityAttributes( $severityMask, $attributes ) { @@ -277,6 +289,7 @@ * * @param array(string => string) $attributes * Array with attribute strings. + * @return void */ public function setSourceAttributes ( $sources, $attributes ) { @@ -284,13 +297,14 @@ } /** - * This method can be added as error_handler. The trigger_error method can be - * used to add messages to the log. + * This method can be set as error_handler if you want to be able to log using + * trigger_error. * * It is advicable to add your own error handler method, and call the - * LogHandler when needed. See for example the following code: + * LogHandler when needed. + * + * Example: * <code> - * * function MyErrorHandler($errno, $errstr, $errfile, $errline) * { * switch ($errno) @@ -310,6 +324,11 @@ * </code> * * See the PHP documentation for more information. + * @param int $errno + * @param int $erstr + * @param string $errfile + * @param int $errline + * @return void */ public static function LogHandler( $errno, $errstr, $errfile, $errline ) { @@ -322,11 +341,10 @@ } /** - * Returns the type name of a given severity. + * Returns the type name of the severity $severity. * * @param int $severity The severity that should be returned as string. - * - * @returns string The name of the severity. + * @return string The name of the severity. */ public static function getSeverityName( $severity ) { Modified: packages/EventLog/trunk/src/log_message.php =================================================================== --- packages/EventLog/trunk/src/log_message.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/log_message.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -9,8 +9,7 @@ */ /** - * Parses a message usually given to the trigger_error method. Properties will - * be set according to the message. + * Holds a log message and provides functionality to manipulate it. * * @package EventLog * @version //autogentag// @@ -18,14 +17,20 @@ class ezcLogMessage { /** - * @var array - * An array that contains the properties of this object. + * Holds the properties of this class. + * + * @var array(string=>mixed) */ protected $properties = array(); /** - * Property set + * Sets the property $name to $value. + * + * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @param string $name + * @param mixed $value + * @return void */ public function __set( $name, $value ) { @@ -47,7 +52,11 @@ } /** - * Property get + * Returns the property $name. + * + * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @param string $name + * @return mixed */ public function __get( $name ) { @@ -69,16 +78,14 @@ } /** - * Constructs the ezcLogMessage and parses a message. + * Constructs the ezcLogMessage from the message $message and $severity, $defaultSource and $defaultCategory. * - * @param string $message The message given to the trigger_error - * method. - * @param int $severity The severity used by PHP. - * @param string $defaultSource Use this source when not given in the - * message itself. - * @param string $defaultCategory Use this category when not give in the - * message itself. + * $message is parsed by parseMessage() and must be in the format it accepts. * + * @param string $message + * @param int $severity + * @param string $defaultSource Use this source when not given in the message itself. + * @param string $defaultCategory Use this category when not give in the message itself. */ public function __construct( $message, $severity, $defaultSource, $defaultCategory ) { @@ -86,15 +93,18 @@ } /** - * Parses the message and sets the properties according to the parsed message. + * Parses the message $message and $severity, $defaultSource and $defaultCategory and sets the properties of this object accordingly. * - * @param string $message The message given to the trigger_error - * method. - * @param int $severity The severity used by PHP. - * @param string $defaultSource Use this source when not given in the - * message itself. + * Parses a message usually given to the trigger_error method. Properties will + * be set according to the message. + * + * @param string $message + * @param int $severity + * @param string $defaultSource Use this source when not given in the + * message itself. * @param string $defaultCategory Use this category when not give in the * message itself. + * @return void */ public function parseMessage( $message, $severity, $defaultSource, $defaultCategory ) { Modified: packages/EventLog/trunk/src/map.php =================================================================== --- packages/EventLog/trunk/src/map.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/map.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -6,15 +6,15 @@ * @version //autogentag// * @copyright Copyright (C) 2005 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License + * @access private */ /** - * Map a mixed variable to an eventType, eventSource, and eventCategory. + * Fast mapping of a mixed variable to an eventType, eventSource and eventCategory. * - * This class is going to be used in the log functionality. - * Since the writers are going to be attached to this Map, the getObject - * method should be really fast because every Log message will check it's - * writer. + * This class is used in ezcLog to map writers to the log messages they + * are supposed to write. It is important that the get() method is extremely + * fast since it will be called for each log message. * * If every combination of eventTypes, eventSources, and eventCategories are * combined (product) and placed in one hash-table. The table grows too fast. @@ -31,13 +31,15 @@ * * @package EventLog * @version //autogentag// + * @access private */ class ezcLogMap { /** - * @var array(integer => bitmask) - * Hashtable with binds a single eventType to a bitmask. The possible - * key-values are: 1, 2, 4, 8, ... + * Hashtable that binds a single eventType to a bitmask. The possible + * key-values are: 1, 2, 4, 8, ... + * + * @var array(integer=>bitmask) */ protected $structure; @@ -48,9 +50,9 @@ } /** - * Add an object to the map. The map binds the product of the given event - * parameters to the given object: + * Map the object $object to the given $eventTypeMask, $eventSources and $eventCategories. * + * Example: * <code> * [ eventType x eventSource x eventCategory ] |-> [ object ] * </code> @@ -62,7 +64,7 @@ * * @return void */ - public function map( $eventTypeMask, $eventSources, $eventCategories, $object ) + public function map( $eventTypeMask, array $eventSources, array $eventCategories, $object ) { $eventTypes = $this->getMaskArray( $eventTypeMask ); $result = array( $object ); @@ -79,20 +81,24 @@ { $eventCategories = array( "*" ); } - $this->createMinimumHash( $eventCategories, $result, $c ); - $this->createMinimumHash( $eventSources, $c, $s ); - $this->createMinimumHash( $eventTypes, $s, $new ); + $c = $this->createMinimumHash( $eventCategories, $result ); + $s = $this->createMinimumHash( $eventSources, $c ); + $new = $this->createMinimumHash( $eventTypes, $s ); $this->mergeHash( $new, $this->structure, $history ); } /** - * MISSING DOCS + * Unmap the object $object to the given $eventTypeMask, $eventSources and $eventCategories. * - * FIXME: Merge some of the code in this function with the one above into a - * new private function, they seem to be doing mostly the same + * @param integer $eventTypeMask + * @param array(string) $eventSources + * @param array(string) $eventCategories + * @param object $object + * + * @return void */ - public function unmap( $eventTypeMask, $eventSources, $eventCategories, $object) + public function unmap( $eventTypeMask, array $eventSources, array $eventCategories, $object) { $eventTypes = $this->getMaskArray( $eventTypeMask ); @@ -111,28 +117,36 @@ $eventCategories = array( "*" ); } - $this->createMinimumHash( $eventCategories, $result, $c ); - $this->createMinimumHash( $eventSources, $c, $s ); - $this->createMinimumHash( $eventTypes, $s, $new ); + $c = $this->createMinimumHash( $eventCategories, $result ); + $s = $this->createMinimumHash( $eventSources, $c ); + $new = $this->createMinimumHash( $eventTypes, $s ); $this->unmergeHash( $this->structure, $new, $history ); } /** - * Creates a hash from an array and a value. The result will be placed in - * the $result parameter. + * Fills the array $out with the keys $inKeys and the value $inValue. * + * @param array inKeys + * @param mixed $inValue + * @param array &$out + * @return array */ - protected function createMinimumHash( $inKeys, $inValue, &$out ) + protected function createMinimumHash( array $inKeys, $inValue ) { foreach ( $inKeys as $key ) { $out[$key] = $inValue; } + return $out; } - + /** + * + * + * @return void + **/ protected function mergeSingle( &$in, &$history ) { $extra = $this->get( $history[0], $history[1], $history[2] ); @@ -257,7 +271,9 @@ /** - * Returns the set bits in an array + * Returns the bits set in $mask as separate values in an array. + * + * @return array(int) */ protected function getMaskArray( $mask ) { @@ -277,8 +293,7 @@ } /** - * Returns an array with objects that belongs to the given key: - * [ eventType, eventSource, eventCategory ]. + * Returns an array with objects are mapped to the key generated by $eventType, $eventSource and $eventCategory. * * The eventType is an integer from in the range: 2^x with x -> N+. * (1, 2, 4, 8, 16, ... ) @@ -286,7 +301,6 @@ * @param integer $eventType * @param string $eventSource * @param string $eventCategory - * * @return array(object). */ public function get( $eventType, $eventSource, $eventCategory) Modified: packages/EventLog/trunk/src/writers/writer_database.php =================================================================== --- packages/EventLog/trunk/src/writers/writer_database.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/writers/writer_database.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -9,7 +9,7 @@ */ /** - * Writes the log messages to the database. + * Writes log messages to the database. * * @package EventLog * @version //autogentag// @@ -26,16 +26,21 @@ private $defaultTable = false; /** - * Construct a new database log-writer. + * Construct a new database log-writer. * - * This constructor is a tie-in. + * You can set the default table to write to with the $defaultTable parameter. + * If $databaseInstance is given, that instance will be used for writing. If it + * is ommitted the default database instance will be retrieved. * - * @param Database $databaseInstance - * An instance of the database that should be used. + * This constructor is a tie-in. + * + * @param string $defaultTable + * @param ezcDbHandler $databaseInstance + * */ - public function __construct( $defaultTable = false, $databaseInstance = false ) + public function __construct( $defaultTable = false, ezcDbHandler $databaseInstance = null ) { - if ( $databaseInstance === false ) + if ( $databaseInstance === null ) { $this->db = ezcDbInstance::get(); } @@ -54,6 +59,14 @@ $this->category = "category"; } + /** + * Sets the property $name to $value. + * + * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @param string $name + * @param mixed $value + * @return void + */ public function __set( $name, $value ) { switch ( $name ) @@ -68,6 +81,13 @@ } } + /** + * Returns the property $name. + * + * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @param string $name + * @return mixed + */ public function __get( $name ) { switch ( $name ) @@ -84,32 +104,25 @@ } /** - * Writes a log message to the log writer. + * Writes the message $message to the log. * * The writer can use the severity, source, and category to filter the * incoming messages and determine the location where the messages should * be written. * + * $optional may contain extra information that can be added to the log. For example: + * line numbers, file names, usernames, etc. + * * @param string message - * The message that should be written. - * * @param int severity - * The severity or type of the message. These numbers can be - * resolved by the ezcLog::getSeverityName() method. + * ezcLog:: DEBUG, SUCCES_AUDIT, FAIL_AUDIT, INFO, NOTICE, WARNING, ERROR or FATAL. * + * @throws ezcLogWriterException when the log writer was unable to write + * the log message. * $param string source - * The source of the message. - * * @param string category - * The category of the message. - * * @param array(string=>string) optional - * Extra information that can be added to the log. For example: - * line numbers, file names, usernames, etc. - * - * - * @throws ezcLogWriterException when the log writer was unable to write - * the log message. + * @return void */ public function writeLogMessage( $message, $severity, $source, $category, $optional = array() ) { @@ -168,7 +181,7 @@ * Returns an array that describes the coupling between the logMessage * information and the columns in the database. * - * @returns array(string=>string) + * @return array(string=>string) */ public function getColumnTranslations() { Modified: packages/EventLog/trunk/src/writers/writer_file.php =================================================================== --- packages/EventLog/trunk/src/writers/writer_file.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/writers/writer_file.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -9,7 +9,7 @@ */ /** - * Writes the log messages to a file + * Writes log messages to a file. * * @package EventLog * @version //autogentag// @@ -17,49 +17,62 @@ abstract class ezcLogWriterFile implements ezcLogWriter { /** - * @var array(resource) Contains all the open files. The first file in the - * array is always the default file. + * Contains all the open files. The first file in the + * array is always the default file. + * + * @var array(resource) */ protected $openFiles; /** - * @var ezcLogMap Keeps track of which group of messages should be stored - * in which file. + * Keeps track of which group of messages should be stored + * in which file. + * + * @var ezcLogMap */ protected $fileMap; /** - * @var string Directory where the log files should be placed. + * Directory where the log files should be placed. + * + * @var string */ protected $logDirectory; /** - * @var integer Maximum log rotation file size. + * Maximum file size before rotation. + * + * @var int */ protected $maxSize; /** - * @var integer Maximum log rotation files with the same name. + * Maximum log rotation files with the same name. + * + * When rotating and the max limit is reached, the oldest log + * is discarded. + * + * @var int */ protected $maxFiles; /** - * Constructs and initializes the writer object. + * Constructs an ezcLogFileWriter to write to the directory $logDirectory. * + * If you set $defaultFile log messages that don't have any specific + * file related to them will be written to this file. If $defaultFile is + * ommited and such a situation occurs the log message will be discarded. * - * @param string $logDirectory Directory where the log files are stored. + * You can set $maxLogRotationSize to specify the maximum size of a logfile + * before it is rotated. With $maxLogFiles you can set the maximum number + * of rotated log files. If needed, the oldest rotated log will be replaced. * - * @param string $defaultFile If the default file is not set to null - * then to this file will be written when - * there is no writer attached to the - * specific log. - * - * @param string $maxLogRotationSize Set the maximum log rotation size. - * - * @param string $maxLogFiles Set the maximum number of log files with - * the same name. + * @param string $logDirectory + * @param string $defaultFile + * @param string $maxLogRotationSize + * @param string $maxLogFiles */ public function __construct( $logDirectory, $defaultFile = null, $maxLogRotationSize = 204800, $maxLogFiles = 3 ) { @@ -77,7 +90,7 @@ } /** - * Destructs the object and will close all open file handles. + * Destructs the object and closes all open file handles. */ public function __destruct() { @@ -107,15 +120,14 @@ //public abstract function writeLogEntry( $logData ); /** - * This method writes the actual log message to a file. + * This method writes log message $string to a file. * + * @throws ezcLogWriterException if it was not possible to write to the log file. * @param integer $eventType * @param string $eventSource * @param string $eventCategory - * @param string $string String that should be written to the log - * file. - * - * @throws ezcLogWriterException + * @param string $string + * @return void */ protected function write( $eventType, $eventSource, $eventCategory, $string ) { @@ -144,7 +156,11 @@ } /** - * Open file and rotate log automatically. + * Opens a file and returns the filehandle. + * + * If needed, the file will be rotated before it is opened. + * + * @return resource */ protected function openFile( $fileName ) { @@ -172,7 +188,9 @@ } /** - * Rotate log. + * Rotates a log and returns true upon success. + * + * @return bool */ protected function rotateLog( $fileName ) { @@ -205,25 +223,30 @@ /** - * Assigns a filename to a specific group of messages. + * Maps the filename $fileName to the messages specified by $eventTypeMask, $eventSources and $eventCategories. * - * @returns boolean True is returned when the filename is writable and - * correctly bound to a group of messages. - * - * <code> - * assignGroup( (SUCCESS_AUDIT | FAILED_AUDIT), array(), array( "Login/Logout" ), "Security" ) - * assignGroup( (ERROR | FATAL), array(), array(), "error" ) - * assignGroup( DEBUG, array( "Paynet" ), array(), "paynet_debug" ); - * </code> + * When a log message matching the parameters should be written, it will be written to the specified file. + * + * @param int $eventTypeMask + * @param array(string) $eventSources + * @param array(string) $eventCategories + * @return void */ - public function logTo( $eventTypeMask, $eventSources, $eventCategories, $fileName ) + public function logTo( $eventTypeMask, array $eventSources, array $eventCategories, $fileName ) { $fh = $this->openFile( $fileName ); $this->fileMap->map( $eventTypeMask, $eventSources, $eventCategories, $fh ); } - - public function logNotTo( $eventTypeMask, $eventSources, $eventCategories, $fileName ) + /** + * Unmaps the filename $fileName to the messages specified by $eventTypeMask, $eventSources and $eventCategories. + * + * @param int $eventTypeMask + * @param array(string) $eventSources + * @param array(string) $eventCategories + * @return void + */ + public function logNotTo( $eventTypeMask, array $eventSources, array $eventCategories, $fileName ) { $this->fileMap->unmap( $eventTypeMask, $eventSources, $eventCategories, $this->openFiles[$fileName] ); } Modified: packages/EventLog/trunk/src/writers/writer_unix_file.php =================================================================== --- packages/EventLog/trunk/src/writers/writer_unix_file.php 2005-12-12 18:33:21 UTC (rev 1342) +++ packages/EventLog/trunk/src/writers/writer_unix_file.php 2005-12-12 19:21:17 UTC (rev 1343) @@ -9,7 +9,7 @@ */ /** - * Writes the log messages to file in Unix style. + * Writes the log messages to a file in Unix style. * * @package EventLog * @version //autogentag// -- svn-components mailing list svn-components@lists.ez.no http://lists.ez.no/mailman/listinfo/svn-components
