Author: Frederik Holljen
Date: 2005-12-12 21:59:22 +0100 (Mon, 12 Dec 2005)
New Revision: 1344
Log:
Doc update and review
Added:
packages/Debug/trunk/review.txt
Modified:
packages/Debug/trunk/src/debug.php
packages/Debug/trunk/src/debug_message.php
packages/Debug/trunk/src/debug_structure.php
packages/Debug/trunk/src/debug_timer.php
packages/Debug/trunk/src/interfaces/reporter.php
packages/Debug/trunk/src/reporters/html_reporter.php
packages/Debug/trunk/src/writers/memory_writer.php
packages/Debug/trunk/tests/debug_test.php
Added: packages/Debug/trunk/review.txt
===================================================================
--- packages/Debug/trunk/review.txt 2005-12-12 19:21:17 UTC (rev 1343)
+++ packages/Debug/trunk/review.txt 2005-12-12 20:59:22 UTC (rev 1344)
@@ -0,0 +1,27 @@
+Review Frederik
+===============
+ezcDebug - lacks examples
+ezcDebug - TODO about recursive timers: yes, ignore or throw an exception. I
think ignore is ok.
+ezcDebug - Lacks a destructor. When this object is removed it should also
remove itself from the log.
+
+ezcDebug::startTimer - what are you supposed to use source and group for?
+ezcDebug::switchTimer - Needs an example. How is this supposed to be used.
+
+ezcDebug::stopTimer - what happens if you call this with a null paramter and
several timers are running?
+ezcDebugTimer::switchTimer - same as above, I think we should use exceptions
here....
+ezcDebugTimer::getStructure - renama to e.g getTimeData.
+
+ezcDebugReporter - I'd rename this class as I expect a reporter to retrieve
information as well. What about ezcDebugOutputFormatter. I'd also rename
getOutput to generateOutput.
+ezcDebugReporter - Format of $writerData?
+
+ezcDebugStructure --> ezcDebugMessage?
+ezcDebugStructure --> Documentation of properties
+ezcDebugStructure - AFAIK ezcMemoryWriter and ezcDebugTimer both uses this
structure but stores different information in it. This is liking using an
array, why not split this into two well documented structs?
+
+ezcDebugWriterMemory - Should be removed?
+
+ezcDebugFormatterHTML - empty, should be removed?
+
+ezcDebugHtmlFormatter::getLog/getOuput - format of $writerData
+ezcDebugHtmlFormatter::getGroups - what exactly does it do?
+ezcDebugHtmlFormatter::addElement - what exactly does it do?
\ No newline at end of file
Property changes on: packages/Debug/trunk/review.txt
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: packages/Debug/trunk/src/debug.php
===================================================================
--- packages/Debug/trunk/src/debug.php 2005-12-12 19:21:17 UTC (rev 1343)
+++ packages/Debug/trunk/src/debug.php 2005-12-12 20:59:22 UTC (rev 1344)
@@ -12,7 +12,7 @@
/**
* The main debug API.
*
- * TODO:
+ * TODO:
* What to do with recursive timers? Ignore when someone tries to start the
* new timer with the same name.
*
@@ -21,34 +21,63 @@
*/
class ezcDebug
{
+ /**
+ * Instance of the singleton ezcDebug object.
+ *
+ * Use the getInstance() method to retrieve the instance.
+ *
+ * @var ezcDebug
+ */
private static $instance = null;
/**
+ * The reporter that generates the debug output.
+ *
* @var ezcDebugFormatter
*/
private $reporter = null;
/**
+ * A pointer to the logging system.
+ *
* @var ezcLog
*/
private $log = null;
/**
+ * The timing object used to store timing information.
+ *
* @var ezcDebugTimer
*/
private $timer = null;
/**
+ * The writer that gathers and holds debug ouput until it is written.
+ *
* @var ezcLogWriter
*/
private $writer = null;
+ /**
+ * Debug level ERROR.
+ */
const ERROR = 1;
+
+ /**
+ * Debug level WARNING.
+ */
const WARNING = 2;
+
+ /**
+ * Debug level NOTICE..
+ */
const NOTICE = 3;
/**
- * Constructs an new Debug class and attaches it to the log object.
+ * Constructs an new debug object and attaches it to the log object.
+ *
+ * When the ezcDebug instance is created it is automatically added to the
instance
+ * of ezcLog.
*/
private function __construct()
{
@@ -72,8 +101,11 @@
/**
* Returns the instance of the class.
+ *
+ * When the ezcDebug instance is created it is automatically added to the
instance
+ * of ezcLog.
*
- * @returns Instance of this class.
+ * @return ezcDebug
*/
public static function getInstance()
{
@@ -86,17 +118,22 @@
}
/**
- * Set the formatter for the output.
+ * Sets the formatter $reporter for the output.
*
- * The HTML formatter is set by default.
+ * If no reporter is set ezcDebugHtmlReporter will be used by default.
+ *
+ * @param ezcDebugReporter $reporter
+ * @return void
*/
- public function setReporter( $reporter )
+ public function setReporter( ezcDebugReporter $reporter )
{
$this->reporter = $reporter;
}
/**
- * Get the formatted output.
+ * Returns the formatted debug output.
+ *
+ * @return string
*/
public function getOutput()
{
@@ -108,12 +145,13 @@
/**
- * Starts the timer.
+ * Starts the timer with the identifier $name.
*
- * @param string name Name of the timer.
- * @param string source Source of the timer.
- * @param string group Group or category. To which group belongs the
- * timer.
+ * Use $source to set the source of the timer and the $group group.
+ *
+ * @param string name
+ * @param string source
+ * @param string group
* @return void
*/
public function startTimer( $name, $source, $group )
@@ -127,6 +165,7 @@
* @param string $newName Name of the new timer.
* @param string $oldName The previous timer that must be stopped.
* Only needed when multiple timers are running.
+ * @return void
*/
public function switchTimer( $newName, $oldName = false )
{
@@ -134,9 +173,12 @@
}
/**
- * Stop the timer
+ * Stops the timer identified by $name.
*
- * @param $name Need to supply a name only when multiple timers are
running.
+ * $name can be ommited if only one timer is running.
+ *
+ * @param $name
+ * @return void
*/
public function stopTimer( $name = false )
{
@@ -144,14 +186,18 @@
}
/**
- * Forward the messages to the log.
+ * Writes the debug message $message with verbosity $verbosity.
*
+ * @param string $message
+ * @param int $verbosity
+ * @param array(string=>string) $extraInfo
+ * @return void
*/
public function log( $message, $verbosity, array $extraInfo = array() )
{
// Add the verbosity
$extraInfo = array_merge( array( "verbosity" => $verbosity ),
$extraInfo );
- return $this->log->log( $message, ezcLog::DEBUG, $extraInfo );
+ $this->log->log( $message, ezcLog::DEBUG, $extraInfo );
}
/**
@@ -177,6 +223,14 @@
* <code>
* trigger_error( "[Paynet, templates] Cannot load template",
E_USER_WARNING );
* </code>
+ *
+ * See the PHP documentation of trigger_error for more information.
+ *
+ * @param int $errno
+ * @param int $erstr
+ * @param string $errfile
+ * @param int $errline
+ * @return void
*/
public static function debugHandler( $errno, $errstr, $errfile,
$errline )
{
@@ -191,6 +245,12 @@
}
+ /**
+ * Returns the type name of the verbosity $verbosity.
+ *
+ * @param int $severity
+ * @return string
+ */
public static function getVerbosityName( $verbosity )
{
switch ( $verbosity )
Modified: packages/Debug/trunk/src/debug_message.php
===================================================================
--- packages/Debug/trunk/src/debug_message.php 2005-12-12 19:21:17 UTC (rev
1343)
+++ packages/Debug/trunk/src/debug_message.php 2005-12-12 20:59:22 UTC (rev
1344)
@@ -9,8 +9,7 @@
*/
/**
- * Parses a message usually given to the trigger_error method. Properties will
- * be set according to the message.
+ * Holds a debug message and provides functionality to manipulate it.
*
* @package Debug
* @version //autogentag//
@@ -18,7 +17,12 @@
class ezcDebugMessage extends ezcLogMessage
{
/**
- * 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 )
{
@@ -32,7 +36,11 @@
}
/**
- * Property get
+ * Returns the property $name.
+ *
+ * @throws ezcBasePropertyNotFoundException if the property does not exist.
+ * @param string $name
+ * @return mixed
*/
public function __get( $name )
{
@@ -47,16 +55,13 @@
}
/**
- * Constructs the ezcLogMessage instance and parses a message.
+ * Constructs the ezcDebugMessage from the message $message and $severity,
$defaultSource and $defaultCategory. *
+ * $message is parsed by parseMessage() and must be in the format it
accepts.
*
- * @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.
- *
+ * @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 )
{
@@ -64,17 +69,19 @@
}
/**
- * 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 )
{
preg_match(
"/^\s*(?:\[([^,\]]*)(?:,\s(.*))?\])?\s*(?:(\d+):)?\s*(.*)$/", $message,
$matches );
Modified: packages/Debug/trunk/src/debug_structure.php
===================================================================
--- packages/Debug/trunk/src/debug_structure.php 2005-12-12 19:21:17 UTC
(rev 1343)
+++ packages/Debug/trunk/src/debug_structure.php 2005-12-12 20:59:22 UTC
(rev 1344)
@@ -17,13 +17,33 @@
*/
class ezcDebugStructure
{
+ /**
+ * Holds the properties of this class.
+ *
+ * @var array(string=>mixed)
+ */
private $properties = array();
+ /**
+ * 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 )
{
$this->properties[$name] = $value;
}
+ /**
+ * Returns the property $name.
+ *
+ * @throws ezcBasePropertyNotFoundException if the property does not exist.
+ * @param string $name
+ * @return mixed
+ */
public function __get( $name )
{
return $this->properties[ $name ];
@@ -32,6 +52,8 @@
/**
* Generates string output of the debug messages.
*
+ * The output generated is each value listed in the form "'key' =>
'value'".
+ *
* @return string
*/
public function toString()
Modified: packages/Debug/trunk/src/debug_timer.php
===================================================================
--- packages/Debug/trunk/src/debug_timer.php 2005-12-12 19:21:17 UTC (rev
1343)
+++ packages/Debug/trunk/src/debug_timer.php 2005-12-12 20:59:22 UTC (rev
1344)
@@ -7,39 +7,72 @@
* @version //autogentag//
* @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
* @license http://ez.no/licenses/new_bsd New BSD License
+ * @access private
*/
/**
- * The ezcDebugTimer class keeps track of several timers.
+ * The ezcDebugTimer class holds several timers.
*
+ * The timers can be started and stopped individually. The timer data can be
retrieved
+ * with the getStructure method.
+ *
* @package Debug
* @version //autogentag//
+ * @access private
*/
class ezcDebugTimer
{
/**
- * @var array A nice internal structure which stores sources, groups, and
timers.
+ * An internal structure which stores sources, groups, and timers.
+ *
+ * @var array(string=>ezcDebugStructure)
*/
private $timers;
+ /**
+ * Similar to $timers but stores timers that are currently running.
+ *
+ * @var array(string=>ezcDebugStructure)
+ */
private $runningTimers;
+ /**
+ * The total number of running timers.
+ *
+ * @var int
+ */
private $totalRunningTimers;
- private $number;
-
+ /**
+ * Constructs a timer object with no timers.
+ */
public function __construct()
{
$this->reset();
}
+ /**
+ * Resets the timer object to its initial state with no timers.
+ *
+ * @return void
+ */
public function reset()
{
$this->timers = array();
$this->runningTimers = array();
- $this->number = 0;
+ $this->totalRunningTimers = 0;
}
+ /**
+ * Starts the timer identified by $name with the source $source and group
$group and returns true on success.
+ *
+ * If the timer was already started false is returned.
+ *
+ * @param string $name
+ * @param string $source
+ * @param string $group
+ * @return bool
+ */
public function startTimer( $name, $source, $group )
{
if ( !isset( $this->runningTimers[ $name ] ) )
@@ -61,11 +94,14 @@
}
/**
- * Stores the time from the running timer, and starts a new timer.
+ * Stops the timer $oldName and starts the timer $newName and return true
on success.
*
- * @param string $newName Name of the new timer.
- * @param string $oldName The previous timer that must be stopped.
- * Only needed when multiple timers are running.
+ * If the timer $oldName does not exist or if it was ommited with several
timers running
+ * false is returned.
+ *
+ * @param string $newName
+ * @param string $oldName
+ * @return bool
*/
public function switchTimer( $newName, $oldName = false )
{
@@ -92,12 +128,17 @@
$switchStruct->time = microtime( true );
$this->runningTimers[$newName]->switchTime[] = $switchStruct;
+ return true;
}
/**
- * Stop the timer
+ * Stop the timer identified by $name and return true on success.
*
- * @param $name Need to supply a name only when multiple timers are
running.
+ * If the timer $oldName does not exist or if it was ommited with several
timers running
+ * false is returned.
+ *
+ * @param $name
+ * @return bool
*/
public function stopTimer( $name = false )
{
@@ -123,9 +164,9 @@
}
/**
- * Returns an array with the used sources, groups, and timers.
+ * Returns an array with the timer data.
*
- * @return array
+ * @return array(ezcDebugStructure)
*/
public function getStructure()
{
@@ -139,7 +180,14 @@
return $this->timers;
}
-
+ /**
+ * Returns time used per group.
+ *
+ * The time is returned as an array in the format
+ * array( 'groupName' => array( number of ms ) )
+ *
+ * @return array(string=>array(int))
+ */
protected function getGroups()
{
$groups = array();
@@ -149,7 +197,6 @@
}
return $groups;
}
-
}
?>
Modified: packages/Debug/trunk/src/interfaces/reporter.php
===================================================================
--- packages/Debug/trunk/src/interfaces/reporter.php 2005-12-12 19:21:17 UTC
(rev 1343)
+++ packages/Debug/trunk/src/interfaces/reporter.php 2005-12-12 20:59:22 UTC
(rev 1344)
@@ -1,5 +1,4 @@
<?php
-
/**
* File containing the ezcDebugFormatter class.
*
@@ -10,8 +9,7 @@
*/
/**
- * Every class that implements this interface can be used to format
- * timer and writer data to a string.
+ * ezcDebugReporter provides the common interface for all classes writing
debug output.
*
* @package Debug
* @version //autogentag//
@@ -19,12 +17,13 @@
interface ezcDebugReporter
{
/**
- * Returns an string containing the formatted output.
+ * Returns a string containing the formatted output based on $timerData
and $writerData.
*
- * @param array $timerData
+ * @param array(ezcDebugStructure) $timerData
* @param array $writerData
+ * @return string
*/
- function getOutput( $timerData, $writerData );
+ function getOutput( array $timerData, array $writerData );
}
?>
Modified: packages/Debug/trunk/src/reporters/html_reporter.php
===================================================================
--- packages/Debug/trunk/src/reporters/html_reporter.php 2005-12-12
19:21:17 UTC (rev 1343)
+++ packages/Debug/trunk/src/reporters/html_reporter.php 2005-12-12
20:59:22 UTC (rev 1344)
@@ -8,19 +8,32 @@
* @license http://ez.no/licenses/new_bsd New BSD License
*/
-/**
- * ezcDebugFormatterHTML class implements a HTML debug formatter in order
- * to create from the Timer and Writer datastructures HTML.
- *
- * This class implements the ezcDebugFormatter interface.
+/**
+ * ezcDebugFormatterHTML class implements a HTML debug formatter that outputs
+ * debug information nicely formated for inclusion on your web page.
*
+ * Default color mapping:
+ * - NOTICE - green
+ * - WARNING - orange
+ * - ERROR - red
+ *
* @package Debug
* @version //autogentag//
- */
+ */
class ezcDebugHtmlReporter implements ezcDebugReporter
{
+ /**
+ * Stores a mapping between the a verbosity level and the color to print
it with.
+ *
+ * Format array(verbosity_level=>'color_name_using_css_names')
+ *
+ * @var array(int=>string)
+ */
private $verbosityColors = array();
-
+
+ /**
+ * Constructs a new HTML reporter.
+ */
public function __construct()
{
$this->verbosityColors[ezcDebug::NOTICE] = 'green';
@@ -28,27 +41,47 @@
$this->verbosityColors[ezcDebug::ERROR] = 'red';
}
+ /**
+ * Sets the output $color of debug messages of the verbosity $verbosity.
+ *
+ * $color must be specified in a CSS color value.
+ * $verbosity is one of ezcDebug:: NOTICE, WARNING or ERROR.
+ *
+ * @param int $verbosity
+ * @param string $color
+ * @return void
+ */
public function setVerbosityColor( $verbosity, $color )
{
$this->verbosityColors[$verbosity] = $color;
}
- /**
- * Returns the HTML output of the combined data structures.
- */
- public function getOutput( $writerData, $timerData )
+ /**
+ * Returns a string containing the HTML formatted output based on
$timerData and $writerData.
+ *
+ * @param array(ezcDebugStructure) $timerData
+ * @param array $writerData
+ * @return string
+ */
+ public function getOutput( array $writerData, array $timerData )
{
$str = '';
$str .= "<style type=\"text/css\">[EMAIL PROTECTED]
url(\"debug.css\");\n</style>\n\n";
$str .= "<table cellspacing='0'>\n";
-
+
$str .= $this->getLog( $writerData );
$str .= $this->getTimingsAccumulator( $timerData );
return $str;
}
- public function getLog( $writerData )
+ /**
+ * Returns a string containing the HTML formatted output based on
$writerData.
+ *
+ * @param array $writerData
+ * @return string
+ */
+ public function getLog( array $writerData )
{
$str = '';
foreach ( $writerData as $w )
@@ -67,7 +100,13 @@
$str .= "</table>\n";
}
- public function getTimingsAccumulator( $timerData )
+ /**
+ * Returns a string containing the HTML formatted output based on
$timerData.
+ *
+ * @param array(ezcDebugStructure) $timerData
+ * @return string
+ */
+ public function getTimingsAccumulator( array $timerData )
{
$groups = $this->getGroups( $timerData );
@@ -106,7 +145,13 @@
return $str;
}
- protected function getGroups( $timers )
+ /**
+ *
+ *
+ * @param array(ezcDebugStructure)
+ * @return array(string)
+ */
+ protected function getGroups( array $timers )
{
$groups = array();
foreach ( $timers as $time )
@@ -123,7 +168,7 @@
//$groups[$time->group]->elements[] = $time;
$this->addElement( $groups[$time->group]->elements, $time );
-
+
$groups[$time->group]->count++;
$groups[$time->group]->elapsedTime += $time->elapsedTime;
$groups[$time->group]->startTime = min(
$groups[$time->group]->startTime, $time->startTime );
@@ -133,6 +178,9 @@
return $groups;
}
+ /**
+ * @return void
+ */
protected function addElement( &$element, $timeStruct )
{
if ( !isset( $element[$timeStruct->name] ) )
Modified: packages/Debug/trunk/src/writers/memory_writer.php
===================================================================
--- packages/Debug/trunk/src/writers/memory_writer.php 2005-12-12 19:21:17 UTC
(rev 1343)
+++ packages/Debug/trunk/src/writers/memory_writer.php 2005-12-12 20:59:22 UTC
(rev 1344)
@@ -20,10 +20,17 @@
class ezcDebugMemoryWriter implements ezcLogWriter
{
/**
- * Internal structure to keep the log messages.
+ * Internal structure to hold the log messages.
+ *
+ * @var array(ezcDebugStructure)
*/
private $logData = array();
+ /**
+ * Resets the writer to its initial state.
+ *
+ * @return void
+ */
public function reset()
{
$this->logData = array();
@@ -33,8 +40,20 @@
/**
* Writes a log entry to the internal memory structure.
*
- * @param string $group
- * @param array $logData
+ * The writer can use the severity, source, and category to filter the
+ * incoming messages and determine the location where the messages should
+ * be written.
+ *
+ * $extraInfo 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
+ * ezcLog:: DEBUG, SUCCES_AUDIT, FAIL_AUDIT, INFO, NOTICE,
WARNING, ERROR or FATAL.
+ * $param string $source
+ * @param string $category
+ * @param array(string=>string) $optional
+ * @return void
*/
public function writeLogMessage( $message, $severity, $source, $category,
$extraInfo = array() )
{
@@ -56,7 +75,11 @@
$this->logData[] = $log;
}
-
+ /**
+ * Returns the log messages stored in memory.
+ *
+ * @return array(ezcDebugStructure)
+ */
public function getStructure()
{
return $this->logData;
Modified: packages/Debug/trunk/tests/debug_test.php
===================================================================
--- packages/Debug/trunk/tests/debug_test.php 2005-12-12 19:21:17 UTC (rev
1343)
+++ packages/Debug/trunk/tests/debug_test.php 2005-12-12 20:59:22 UTC (rev
1344)
@@ -108,9 +108,9 @@
}
-class TestReporter
+class TestReporter implements ezcDebugReporter
{
- public function getOutput($timerData, $writerData)
+ public function getOutput( array $timerData, array $writerData)
{
return array( $timerData, $writerData );
}
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
