LOG4PHP-163 Fixed the LoggerPatternConverter so that trimming is by default done...
authorIvan Habunek <ihabunek@apache.org>
Mon, 8 Oct 2012 08:23:07 +0000 (08:23 +0000)
committerIvan Habunek <ihabunek@apache.org>
Mon, 8 Oct 2012 08:23:07 +0000 (08:23 +0000)
git-svn-id: https://svn.apache.org/repos/asf/logging/log4php/trunk@1395467 13f79535-47bb-0310-9956-ffa450edef68

src/changes/changes.xml
src/main/php/helpers/LoggerPatternParser.php
src/site/xdoc/docs/layouts/pattern.xml

index 8540961..666469c 100644 (file)
@@ -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>
index 79dc140..a2ed911 100644 (file)
@@ -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;
        }
 }
-
index 06264d8..7b3a6cf 100644 (file)
                                <p><strong>Conversion pattern</strong> is a string which controls the formatting of logging \r
                                events. It controls how logging events will be transformed into strings by the layout.</p>\r
                        \r
-                               <p>The conversion pattern is closely related to the conversion pattern of the \r
-                               <a href="http://www.cplusplus.com/reference/clibrary/cstdio/printf" class="external">printf</a> \r
-                               function in C(++). It is composed of literal text and format control expressions called <em>conversion \r
-                               specifiers</em>.</p>\r
+                               <p>The conversion pattern is closely related to the conversion pattern of the PHP \r
+                               <a href="http://www.php.net/manual/en/function.sprintf.php" class="external">sprintf</a> function. \r
+                               It is composed of literal text and format control expressions called <em>conversion specifiers</em>.\r
+                               </p>\r
                                \r
                                <p>A conversion specifier begins with a percent sign (%) and is followed by a <em>conversion word</em>.\r
                                Some conversion words require one or more <em>options</em> to be given. These are specified in braces after the \r
                                        </tr>\r
                                        <tr>\r
                                                <td>\r
+                                                       <p><strong>%ex</strong></p>\r
+                                                       <p><strong>%exception</strong></p>\r
+                                                       <p><strong>%throwable</strong></p>\r
+                                               </td>\r
+                                               <td>\r
+                                                       <p>The exception associated with the logging event, along with it's stack trace. If\r
+                                                       there is no exception, evalutates to an empty string.</p>\r
+                                               </td>\r
+                                       </tr>\r
+                                       <tr>\r
+                                               <td>\r
                                                        <p><strong>%F</strong></p>\r
                                                        <p><strong>%file</strong></p>\r
                                                </td>\r
                                it is possible to change the minimum and maximum width and the justifications of each data field.\r
                                </p>\r
                                \r
-                               <p>All format modifiers are optional, and are placed between the percent sign and the conversion \r
-                               word.</p>\r
+                               <p>Both format modifiers are optional, and are placed between the percent sign (%) and the conversion \r
+                               word. These are, in order:</p>\r
                                \r
-                               <p>The first format modifier is the <em>left justification flag</em> which is just the minus (-)\r
-                               character.</p>\r
-                                \r
-                               <p>Then comes the <em>>minimum field width</em> modifier. This is an integer that \r
-                               represents the minimum number of characters to output. If the data item requires fewer characters,\r
-                               it is padded on either the left or the right until the minimum width is reached. The default is to\r
-                               pad on the left (right justify) but you can specify right padding with the left justification flag.\r
-                               The padding character is space. If the data item is larger than the minimum field width, the field\r
-                               is expanded to accommodate the data. The value is never truncated. </p>\r
-                                \r
-                               <p>This behavior can be changed using the <em>maximum field width</em> modifier which is designated\r
-                               by a period (.) followed by an integer. If the data item is longer than the maximum field, then the\r
-                               extra characters are removed from the beginning of the data item and not from the end. For example,\r
-                               it the maximum field width is eight and the data item is ten characters long, then the first two \r
-                               characters of the data item are dropped. This behavior deviates from the printf function in C where\r
-                               truncation is done from the end. </p>\r
+                               <ol>\r
+                                       <li>A <b>minimum width specifier</b>, a number which determines the minimum width of the resulting\r
+                                       string. If the resulting string is shorter that the given number, it will be padded with spaces to\r
+                                       the desired length. By default, the string is right-justified (padded from left), but adding a \r
+                                       "-" sign before the specifier will make it left-justified.</li> \r
+                                       \r
+                                       <li>A <b>maximum widht specifier</b>, a dot (".") followed by a number which determines the maximum\r
+                                       allowed width of the resulting string. If the resulting string is shorter than the given number, it\r
+                                       will be truncated to the maximum width. By default the string is truncated from the right, but \r
+                                       adding a "-" sign before the specifier will cause it to truncate from the left.</li>\r
+                               </ol>\r
                                \r
                                <p>The following table demonstrates various uses of format modifiers:</p>\r
                                \r
                                                <tr>\r
                                                        <td align="center"><strong>%.30logger</strong></td>\r
                                                        <td align="center">none</td>\r
-                                                   <td align="center">left</td>\r
+                                                   <td align="center">right</td>\r
                                                        <td align="center">none</td>\r
                                                        <td align="center">30</td>\r
-                                                       <td>Trim from the beginning if the logger name is longer than 30 characters.</td>\r
+                                                       <td>Trim from the end if the logger name is longer than 30 characters.</td>\r
                                                </tr>\r
                                                <tr>\r
                                                        <td align="center"><strong>%.-30logger</strong></td>\r
                                                        <td align="center">none</td>\r
-                                                   <td align="center">right</td>\r
+                                                   <td align="center">left</td>\r
                                                        <td align="center">none</td>\r
                                                        <td align="center">30</td>\r
-                                                       <td>Trim from the end if the logger name is longer than 30 characters.</td>\r
+                                                       <td>Trim from the beginning if the logger name is longer than 30 characters.</td>\r
                                                </tr>\r
                                                <tr>\r
                                                        <td align="center"><strong>%20.30logger</strong></td>\r
                                                        <td align="center">right</td>\r
-                                                   <td align="center">left</td>\r
+                                                   <td align="center">right</td>\r
                                                        <td align="center">20</td>\r
                                                        <td align="center">30</td>\r
                                                        <td>Left pad with spaces if the logger name is shorter than 20 characters. However, if \r
-                                                       the logger name is longer than 30 characters, then trim from the beginning.</td>\r
+                                                       the logger name is longer than 30 characters, then trim from the end.</td>\r
                                                </tr>\r
                                                <tr>\r
                                                        <td align="center"><strong>%-20.30logger</strong></td>\r
                                                        <td align="center">left</td>\r
-                                                   <td align="center">left</td>\r
+                                                   <td align="center">right</td>\r
                                                        <td align="center">20</td>\r
                                                        <td align="center">30</td>\r
                                                        <td>Right pad with spaces if the logger name is shorter than 20 characters. However, if the\r
-                                                       logger name is longer than 30 characters, then trim from the beginning.</td>\r
+                                                       logger name is longer than 30 characters, then trim from the end.</td>\r
                                                </tr>\r
                                        </tbody>\r
                                </table>\r
                                        </thead>\r
                                        <tbody>\r
                                                <tr>\r
-                                                       <td>[%10.10logger]</td>\r
+                                                       <td>[%10logger]</td>\r
                                                        <td>Foo</td>\r
                                                        <td><code>[&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Foo]</code></td>\r
+                                                       <td>Added padding, right aligned.</td>\r
                                                </tr>\r
                                                <tr>\r
-                                                       <td>[%-10.10logger]</td>\r
+                                                       <td>[%-10logger]</td>\r
                                                        <td>Foo</td>\r
                                                        <td><code>[Foo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;]</code></td>\r
+                                                       <td>Added padding, left aligned.</td>\r
                                                </tr>\r
                                                <tr>\r
-                                                       <td>[%10.10logger]</td>\r
+                                                       <td>[%.10logger]</td>\r
                                                        <td>org.apache.log4php.Foo</td>\r
-                                                       <td><code>[og4php.Foo]</code></td>\r
+                                                       <td><code>[org.apache]</code></td>\r
+                                                       <td>Trimmed from right.</td>\r
                                                </tr>\r
                                                <tr>\r
-                                                       <td>[%10.-10logger]</td>\r
+                                                       <td>[%.-10logger]</td>\r
                                                        <td>org.apache.log4php.Foo</td>\r
-                                                       <td><code>[org.apache]</code></td>\r
+                                                       <td><code>[og4php.Foo]</code></td>\r
+                                                       <td>Trimmed from left.</td>\r
                                                </tr>\r
                                        </tbody>\r
                                </table>\r
@@ -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.\r
 </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>\r
+                               \r
+                               <h4>Logging exceptions</h4>\r
+                               \r
+                               <p>If you wish to log any exception passed to the logging methods, you should add the <code>%ex</code>\r
+                               specifier to the end of your conversion pattern, after <code>%newline</code>. This way, if an exception\r
+                               is loggerd it will be addded to your log below your message.</p> \r
+\r
+                               <p>For example: <code>%date %logger %message%newline%ex</code></p>\r
+                               \r
+                               <p>In the following code, suppose that the work() method can throw an exception. This wolud be a good\r
+                               way to deal with it:</p>\r
+                               \r
+<pre class="prettyprint linenums">\r
+$log = Logger::getLogger('foo');\r
+$log->info("Let's try this");\r
+\r
+try\r
+{\r
+    $foo = new Foo();\r
+    $foo->work(123);\r
+}\r
+catch(Exception $ex)\r
+{\r
+    // Exception is passed as the second parameter\r
+    $log->error("That didn't work", $ex);\r
+}\r
+$log->info("Done.");\r
+</pre>\r
+\r
+                               <p>If work() throws an exception, your log might look something like this:</p>\r
+\r
+<pre>\r
+2012-10-08T10:11:18+02:00 foo Let's try this\r
+2012-10-08T10:11:18+02:00 foo That didn't work\r
+exception 'Exception' with message 'Doesn't work' in D:\work\exceptions.php:38\r
+Stack trace:\r
+#0 D:\work\exceptions.php(29): Bar->work(123)\r
+#1 D:\work\exceptions.php(48): Foo->work(123)\r
+#2 {main}\r
+2012-10-08T10:11:18+02:00 foo Done.\r
+</pre>\r
+\r
+                               <p>The exception, along with the full stack trace ends up in your log. This also works with nested \r
+                               exceptions, the full stack trace is added.</p>\r
                        </subsection>\r
                </section>\r
        </body>\r