Author: ihabunek
Date: Mon Oct 8 08:23:07 2012
New Revision: 1395467
URL: http://svn.apache.org/viewvc?rev=1395467&view=rev
Log:
LOG4PHP-163 Fixed the LoggerPatternConverter so that trimming is by default
done from the right (same as in sprintf()). Improved docs.
Modified:
logging/log4php/trunk/src/changes/changes.xml
logging/log4php/trunk/src/main/php/helpers/LoggerPatternParser.php
logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml
Modified: logging/log4php/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/logging/log4php/trunk/src/changes/changes.xml?rev=1395467&r1=1395466&r2=1395467&view=diff
==============================================================================
--- logging/log4php/trunk/src/changes/changes.xml (original)
+++ logging/log4php/trunk/src/changes/changes.xml Mon Oct 8 08:23:07 2012
@@ -21,6 +21,7 @@
</properties>
<body>
<release version="2.3.0" date="SVN">
+ <action date="2012-10-07" type="fix"
issue="LOG4PHP-163" dev="Ivan Habunek" due-to="Daniel Wong" due-to-email="dan
at dsmwong dot com">LoggerPatternConverter formats max incorrectly</action>
<action date="2012-10-07" type="fix"
issue="LOG4PHP-188" dev="Ivan Habunek">Events logged by upstream loggers even
if disabled by level.</action>
<action date="2012-10-06" type="update"
issue="LOG4PHP-186" dev="Ivan Habunek" due-to="Rasmus Lerdorf"
due-to-email="rasmus at lerdorf dot com">Don't clear the entire stat cache on
an append.</action>
<action date="2012-10-06" type="add"
issue="LOG4PHP-141" dev="Ivan Habunek">Allow setting of a default
renderer.</action>
Modified: logging/log4php/trunk/src/main/php/helpers/LoggerPatternParser.php
URL:
http://svn.apache.org/viewvc/logging/log4php/trunk/src/main/php/helpers/LoggerPatternParser.php?rev=1395467&r1=1395466&r2=1395467&view=diff
==============================================================================
--- logging/log4php/trunk/src/main/php/helpers/LoggerPatternParser.php
(original)
+++ logging/log4php/trunk/src/main/php/helpers/LoggerPatternParser.php Mon Oct
8 08:23:07 2012
@@ -64,7 +64,7 @@ class LoggerPatternParser {
self::ESCAPE_CHAR . // Character which marks
the start of the conversion pattern
'(?P<modifiers>[0-9.-]*)' . // Format modifiers
(optional)
'(?P<word>[a-zA-Z]+)' . // The conversion word
- '(?P<option>{[^}]*})?' . // Conversion option in
braces (optional)
+ '(?P<option>{[^}]*})?' . // Conversion option in
braces (optional)
'/'; // Ending regex pattern
delimiter
}
@@ -229,10 +229,9 @@ class LoggerPatternParser {
if (!empty($parts[1])) {
$maxPart = (integer) $parts[1];
$info->max = abs($maxPart);
- $info->trimLeft = ($maxPart > 0);
+ $info->trimLeft = ($maxPart < 0);
}
return $info;
}
}
-
Modified: logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml
URL:
http://svn.apache.org/viewvc/logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml?rev=1395467&r1=1395466&r2=1395467&view=diff
==============================================================================
--- logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml (original)
+++ logging/log4php/trunk/src/site/xdoc/docs/layouts/pattern.xml Mon Oct 8
08:23:07 2012
@@ -56,10 +56,10 @@
<p><strong>Conversion pattern</strong> is a
string which controls the formatting of logging
events. It controls how logging events will be
transformed into strings by the layout.</p>
- <p>The conversion pattern is closely related to
the conversion pattern of the
- <a
href="http://www.cplusplus.com/reference/clibrary/cstdio/printf";
class="external">printf</a>
- function in C(++). It is composed of literal
text and format control expressions called <em>conversion
- specifiers</em>.</p>
+ <p>The conversion pattern is closely related to
the conversion pattern of the PHP
+ <a
href="http://www.php.net/manual/en/function.sprintf.php";
class="external">sprintf</a> function.
+ It is composed of literal text and format
control expressions called <em>conversion specifiers</em>.
+ </p>
<p>A conversion specifier begins with a percent
sign (%) and is followed by a <em>conversion word</em>.
Some conversion words require one or more
<em>options</em> to be given. These are specified in braces after the
@@ -218,6 +218,17 @@
</tr>
<tr>
<td>
+
<p><strong>%ex</strong></p>
+
<p><strong>%exception</strong></p>
+
<p><strong>%throwable</strong></p>
+ </td>
+ <td>
+ <p>The exception
associated with the logging event, along with it's stack trace. If
+ there is no exception,
evalutates to an empty string.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
<p><strong>%F</strong></p>
<p><strong>%file</strong></p>
</td>
@@ -353,25 +364,20 @@
it is possible to change the minimum and
maximum width and the justifications of each data field.
</p>
- <p>All format modifiers are optional, and are
placed between the percent sign and the conversion
- word.</p>
+ <p>Both format modifiers are optional, and are
placed between the percent sign (%) and the conversion
+ word. These are, in order:</p>
- <p>The first format modifier is the <em>left
justification flag</em> which is just the minus (-)
- character.</p>
-
- <p>Then comes the <em>>minimum field width</em>
modifier. This is an integer that
- represents the minimum number of characters to
output. If the data item requires fewer characters,
- it is padded on either the left or the right
until the minimum width is reached. The default is to
- pad on the left (right justify) but you can
specify right padding with the left justification flag.
- The padding character is space. If the data
item is larger than the minimum field width, the field
- is expanded to accommodate the data. The value
is never truncated. </p>
-
- <p>This behavior can be changed using the
<em>maximum field width</em> modifier which is designated
- by a period (.) followed by an integer. If the
data item is longer than the maximum field, then the
- extra characters are removed from the beginning
of the data item and not from the end. For example,
- it the maximum field width is eight and the
data item is ten characters long, then the first two
- characters of the data item are dropped. This
behavior deviates from the printf function in C where
- truncation is done from the end. </p>
+ <ol>
+ <li>A <b>minimum width specifier</b>, a
number which determines the minimum width of the resulting
+ string. If the resulting string is
shorter that the given number, it will be padded with spaces to
+ the desired length. By default, the
string is right-justified (padded from left), but adding a
+ "-" sign before the specifier will make
it left-justified.</li>
+
+ <li>A <b>maximum widht specifier</b>, a
dot (".") followed by a number which determines the maximum
+ allowed width of the resulting string.
If the resulting string is shorter than the given number, it
+ will be truncated to the maximum width.
By default the string is truncated from the right, but
+ adding a "-" sign before the specifier
will cause it to truncate from the left.</li>
+ </ol>
<p>The following table demonstrates various
uses of format modifiers:</p>
@@ -414,36 +420,36 @@
<tr>
<td
align="center"><strong>%.30logger</strong></td>
<td
align="center">none</td>
- <td align="center">left</td>
+ <td
align="center">right</td>
<td
align="center">none</td>
<td
align="center">30</td>
- <td>Trim from the
beginning if the logger name is longer than 30 characters.</td>
+ <td>Trim from the end
if the logger name is longer than 30 characters.</td>
</tr>
<tr>
<td
align="center"><strong>%.-30logger</strong></td>
<td
align="center">none</td>
- <td
align="center">right</td>
+ <td align="center">left</td>
<td
align="center">none</td>
<td
align="center">30</td>
- <td>Trim from the end
if the logger name is longer than 30 characters.</td>
+ <td>Trim from the
beginning if the logger name is longer than 30 characters.</td>
</tr>
<tr>
<td
align="center"><strong>%20.30logger</strong></td>
<td
align="center">right</td>
- <td align="center">left</td>
+ <td
align="center">right</td>
<td
align="center">20</td>
<td
align="center">30</td>
<td>Left pad with
spaces if the logger name is shorter than 20 characters. However, if
- the logger name is
longer than 30 characters, then trim from the beginning.</td>
+ the logger name is
longer than 30 characters, then trim from the end.</td>
</tr>
<tr>
<td
align="center"><strong>%-20.30logger</strong></td>
<td
align="center">left</td>
- <td align="center">left</td>
+ <td
align="center">right</td>
<td
align="center">20</td>
<td
align="center">30</td>
<td>Right pad with
spaces if the logger name is shorter than 20 characters. However, if the
- logger name is longer
than 30 characters, then trim from the beginning.</td>
+ logger name is longer
than 30 characters, then trim from the end.</td>
</tr>
</tbody>
</table>
@@ -461,24 +467,28 @@
</thead>
<tbody>
<tr>
- <td>[%10.10logger]</td>
+ <td>[%10logger]</td>
<td>Foo</td>
<td><code>[ Foo]</code></td>
+ <td>Added padding,
right aligned.</td>
</tr>
<tr>
- <td>[%-10.10logger]</td>
+ <td>[%-10logger]</td>
<td>Foo</td>
<td><code>[Foo ]</code></td>
+ <td>Added padding, left
aligned.</td>
</tr>
<tr>
- <td>[%10.10logger]</td>
+ <td>[%.10logger]</td>
<td>org.apache.log4php.Foo</td>
-
<td><code>[og4php.Foo]</code></td>
+
<td><code>[org.apache]</code></td>
+ <td>Trimmed from
right.</td>
</tr>
<tr>
- <td>[%10.-10logger]</td>
+ <td>[%.-10logger]</td>
<td>org.apache.log4php.Foo</td>
-
<td><code>[org.apache]</code></td>
+
<td><code>[og4php.Foo]</code></td>
+ <td>Trimmed from
left.</td>
</tr>
</tbody>
</table>
@@ -594,7 +604,51 @@ $logger->warn("Sed sit amet ipsum mauris
2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar]
Message: Sed sit amet ipsum mauris.
</pre>
- <p><code>%server{REMOTE_ADDR}</code> is
equivalent to PHP code <code>$_SERVER['REMOTE_ADDR']</code>.</p>
+ <p><code>%server{REMOTE_ADDR}</code> is
equivalent to PHP code <code>$_SERVER['REMOTE_ADDR']</code>.</p>
+
+ <h4>Logging exceptions</h4>
+
+ <p>If you wish to log any exception passed to
the logging methods, you should add the <code>%ex</code>
+ specifier to the end of your conversion
pattern, after <code>%newline</code>. This way, if an exception
+ is loggerd it will be addded to your log below
your message.</p>
+
+ <p>For example: <code>%date %logger
%message%newline%ex</code></p>
+
+ <p>In the following code, suppose that the
work() method can throw an exception. This wolud be a good
+ way to deal with it:</p>
+
+<pre class="prettyprint linenums">
+$log = Logger::getLogger('foo');
+$log->info("Let's try this");
+
+try
+{
+ $foo = new Foo();
+ $foo->work(123);
+}
+catch(Exception $ex)
+{
+ // Exception is passed as the second parameter
+ $log->error("That didn't work", $ex);
+}
+$log->info("Done.");
+</pre>
+
+ <p>If work() throws an exception, your log
might look something like this:</p>
+
+<pre>
+2012-10-08T10:11:18+02:00 foo Let's try this
+2012-10-08T10:11:18+02:00 foo That didn't work
+exception 'Exception' with message 'Doesn't work' in D:\work\exceptions.php:38
+Stack trace:
+#0 D:\work\exceptions.php(29): Bar->work(123)
+#1 D:\work\exceptions.php(48): Foo->work(123)
+#2 {main}
+2012-10-08T10:11:18+02:00 foo Done.
+</pre>
+
+ <p>The exception, along with the full stack
trace ends up in your log. This also works with nested
+ exceptions, the full stack trace is added.</p>
</subsection>
</section>
</body>
