[Phpgroupware-developers] Logging Statement Guidelines? (long)

[Doug Dicks]

Hello,

Are there any accepted project standards/guidelines for including log 
statements in phpgroupware for debugging purposes? 

I've looked through the errorlog class and understand the 
[severity]-[code], [message] syntax on logging messages, as well as how 
the parameter substitution happens.  I understand the parent-child 
relationship between phpgw_log and phpgw_log_msg.  And have added log 
statements to help me debug.

But I still have general questions like:

When should you log->write() an error as opposed to just creating it on 
the stack via log->error()?
What's the difference between log->error() and log->message()?  Can I 
filter at runtime on severity levels?

I guess I understand how to add logging, but not what is acceptable 
practice for the PHPGroupware project.  Ideally, I'd like to be able to 
contribute my changes back to the application, figuring they'd be useful 
for somebody else.

For example, I'm debugging a problem in 0.9.16.x where my IMAP mailbox 
is not opening successfully.  Looking for imap_open(), I find it in 
class.mail_dcom_imap.inc.php, I see an open method that looks like:

function open($mailbox,$username,$password,$flags=0)
{
   $mailbox = $this->utf7_encode($mailbox);
   return imap_open($mailbox,$username,$password,$flags);
}

I could, if I wanted to, add some logging and error checking like:

function open($mailbox,$username,$password,$flags=0)
{
       $mailbox = $this->utf7_encode($mailbox);
       $GLOBALS['phpgw']->log->message(array(
                             'text' => 'D-EMAIL, Opening IMAP mailbox 
%1 for user %2',
                             'p1'   => $mailbox,
                             'p2'   => $username,
                             'line' => __LINE__,
                             'file' => __FILE__
               )
       );
       $mbox =  imap_open($mailbox,$username,$password,$flags);
       if ( $mbox == false )
       {
               $GLOBALS['phpgw']->log->error(array(
                               'text' => 'E-EMAIL, Failed to open IMAP 
mailbox %1 for user %2',
                               'p1'   => $mailbox,
                               'p2'   => $username,
                               'line' => __LINE__,
                               'file' => __FILE__
                       )
               );
       }
       else
       {
               $GLOBALS['phpgw']->log->message(array(
                               'text' => 'I-EMAIL, Opened IMAP mailbox 
%1 for user %2',
                               'p1'   => $mailbox,
                               'p2'   => $username,
                               'line' => __LINE__,
                               'file' => __FILE__
                       )
               );
       }
       $GLOBALS['phpgw']->log->commit();
       return $mbox;
}

From a debugging standpoint, that worked great for me.  I can see from 
the log in the database that the mailbox is not being set correctly.  
It's {:143}INBOX instead of {mail.revelanttech.com:143}INBOX.

But *should* I do things like this?  In this case, that method is called 
from within class.mail_msg_base.inc.php.  That's a higher-level class, a 
good place for error handling, and indeed it does have some error 
handling.  But it doesn't use the errorlog class.  And it has it's own 
debug log, using email.svc_debug, whatever that is.

So, I'm confused.  And need a bit of guidance. 
                                             

(Note:  In the above example I'd ideally like to be able to filter by 
severity level so if the global level is set to 'E' the debug and info 
messages would never get written to the DB.)
                                                                               

I'm trying out both 0.9.14.x and 0.9.16.x.  We're looking at using it 
both internally and for hosting email, calendar, contacts, forums, and 
time tracking for a client.  And perhaps adding expense tracking as well.

So as I go through and find things that don't work, I'd love to be able 
to add code to log the errors and contribute that back to the project 
(along with any bugfixes / new code). 

Suggestions?

Thanks,

Doug
--
Doug Dicks
Revelant Technologies