Merge pull request #289 in ZP/z-push from...

Merge pull request #289 in ZP/z-push from feature/ZP-972-allow-backends-enable-device-or-user-logs to develop

* commit '74efedde':
  ZP-972 Fixed @access.
  ZP-972 Implement ZLog::SpecialLogUser() to be called before authentication is completed to force the generation of a user log, fixed method descriptions, use Log::unauthMessageCache for all unauthenticated users, fixed ZLog dependency in PrintWBXML, removed ZLog::RequestHeaders(), removed ZLog::SetSpecialLogUsers(), removed ZLog::EnableDeviceLog().
  ZP-972 Add request header also to device specific log, by moving it from index.php to protected method ZLog::RequestHeader and calling it from ZLog::Initialise and ZLog::EnableDeviceLog.
  ZP-972 Use deviceid and authuser from Logger in zlog instead of getting them from Request. Renamed setLogToUserFile to SetLogToUserFile and added it as public to the abstract Log class. Renamed WbxmlDebug to IsWbxmlDebugEnabled. Fixed typos in function descriptions. Replaced tabs with spaces.
  ZP-972 fix WBXML is not logged for LOGUSERLEVEL >= LOGLEVEL_WBXML, if LOGLEVEL < LOGLEVEL_WBXML and $specialLogUsers is not already defined in config.php, because enabled on runtime via ZLog::EnableDeviceLog() or ZLog::setSpecialLogUsers().
  ZP-972 allow backends to enable device or user specific logging.

src/lib/core/zlog.php

@@ -33,14 +33,12 @@ class ZLog {
     static private $logger = null;
 
     /**
-     * Initializes the logging
+     * Initializes the logging.
      *
      * @access public
      * @return boolean
      */
     static public function Initialize() {
-        $logger = self::getLogger();
-
         // define some constants for the logging
         if (!defined('LOGUSERLEVEL'))
             define('LOGUSERLEVEL', LOGLEVEL_OFF);
@@ -48,26 +46,30 @@ class ZLog {
         if (!defined('LOGLEVEL'))
             define('LOGLEVEL', LOGLEVEL_OFF);
 
-        if (!defined('WBXML_DEBUG')) {
-            // define the WBXML_DEBUG mode on user basis depending on the configurations
-            if (LOGLEVEL >= LOGLEVEL_WBXML || (LOGUSERLEVEL >= LOGLEVEL_WBXML && $logger->HasSpecialLogUsers()))
-                define('WBXML_DEBUG', true);
-            else
-                define('WBXML_DEBUG', false);
-        }
+        $logger = self::getLogger();
 
         return true;
     }
 
     /**
-     * Writes a log line
+     * Check if WBXML logging is enabled in current LOG(USER)LEVEL.
+     *
+     * @access public
+     * @return boolean
+     */
+    static public function IsWbxmlDebugEnabled() {
+        return LOGLEVEL >= LOGLEVEL_WBXML || (LOGUSERLEVEL >= LOGLEVEL_WBXML && self::getLogger()->HasSpecialLogUsers());
+    }
+
+    /**
+     * Writes a log line.
      *
      * @param int       $loglevel           one of the defined LOGLEVELS
      * @param string    $message
      * @param boolean   $truncate           indicate if the message should be truncated, default true
      *
      * @access public
-     * @return
+     * @return void
      */
     static public function Write($loglevel, $message, $truncate = true) {
         // truncate messages longer than 10 KB
@@ -91,7 +93,7 @@ class ZLog {
     }
 
     /**
-     * Returns logged information about the WBXML stack
+     * Returns logged information about the WBXML stack.
      *
      * @access public
      * @return string
@@ -101,7 +103,7 @@ class ZLog {
     }
 
     /**
-     * Returns the last message logged for a log level
+     * Returns the last message logged for a log level.
      *
      * @param int       $loglevel           one of the defined LOGLEVELS
      *
@@ -112,6 +114,19 @@ class ZLog {
         return (isset(self::$lastLogs[$loglevel]))?self::$lastLogs[$loglevel]:false;
     }
 
+    /**
+     * If called, the authenticated current user gets an extra log-file.
+     *
+     * If called until the user is authenticated (e.g. at the end of IBackend->Logon()) all log
+     * messages that happened until this point will also be logged.
+     *
+     * @access public
+     * @return void
+     */
+    static public function SpecialLogUser() {
+        self::getLogger()->SpecialLogUser();
+    }
+
     /**
      * Returns the logger object. If no logger has been initialized, FileLog will be initialized and returned.
      *
@@ -153,9 +168,6 @@ class ZLog {
  * Legacy debug stuff
  */
 
-// E_DEPRECATED only available since PHP 5.3.0
-if (!defined('E_DEPRECATED')) define(E_DEPRECATED, 8192);
-
 // TODO review error handler
 function zpush_error_handler($errno, $errstr, $errfile, $errline, $errcontext) {
     if (defined('LOG_ERROR_MASK')) $errno &= LOG_ERROR_MASK;

src/lib/log/filelog.php

@@ -22,6 +22,7 @@
  *
  * Consult LICENSE file for details
  ************************************************/
+
 class FileLog extends Log {
 
     /**
@@ -29,6 +30,12 @@ class FileLog extends Log {
      */
     private $log_to_user_file = false;
 
+    /**
+     * Constructor
+     */
+    public function __construct() {
+    }
+
     /**
      * Get the log user file.
      *
@@ -43,17 +50,19 @@ class FileLog extends Log {
     }
 
     /**
+     * Set user log-file relative to log directory.
+     *
      * @param string $value
+     *
+     * @access private
+     * @return void
      */
     private function setLogToUserFile($value) {
         $this->log_to_user_file = $value;
     }
 
-    public function __construct() {
-    }
-
     /**
-     * Returns the string to be logged
+     * Returns the string to be logged.
      *
      * @param int $loglevel
      * @param string $message
@@ -74,6 +83,15 @@ class FileLog extends Log {
     // Implementation of Log
     //
 
+    /**
+     * Writes a log message to the general log.
+     *
+     * @param int $loglevel
+     * @param string $message
+     *
+     * @access protected
+     * @return void
+     */
     protected function Write($loglevel, $message) {
         $data = $this->buildLogString($loglevel, $message) . PHP_EOL;
         @file_put_contents(LOGFILE, $data, FILE_APPEND);
@@ -83,11 +101,26 @@ class FileLog extends Log {
         }
     }
 
+    /**
+     * Writes a log message to the user specific log.
+     * @param int $loglevel
+     * @param string $message
+     *
+     * @access public
+     * @return void
+     */
     public function WriteForUser($loglevel, $message) {
         $data = $this->buildLogString($loglevel, $message) . PHP_EOL;
         @file_put_contents(LOGFILEDIR . $this->getLogToUserFile(), $data, FILE_APPEND);
     }
 
+    /**
+     * This function is used as an event for log implementer.
+     * It happens when the a call to the Log function is finished.
+     *
+     * @access protected
+     * @return void
+     */
     protected function afterLog($loglevel, $message) {
         if (($loglevel & LOGLEVEL_FATAL) || ($loglevel & LOGLEVEL_ERROR)) {
             $data = $this->buildLogString($loglevel, $message) . PHP_EOL;

src/lib/log/log.php

@@ -68,6 +68,14 @@ abstract class Log {
     private $unauthMessageCache = array();
 
     /**
+     * Constructor
+     */
+    public function __construct() {
+    }
+
+    /**
+     * Returns the current user.
+     *
      * @access public
      * @return string
      */
@@ -76,15 +84,20 @@ abstract class Log {
     }
 
     /**
+     * Sets the current user.
+     *
      * @param string $value
      *
      * @access public
+     * @return void
      */
     public function SetUser($value) {
         $this->user = $value;
     }
 
     /**
+     * Returns the current authenticated user.
+     *
      * @access public
      * @return string
      */
@@ -93,9 +106,12 @@ abstract class Log {
     }
 
     /**
+     * Sets the current authenticated user.
+     *
      * @param string $value
      *
      * @access public
+     * @return void
      */
     public function SetAuthUser($value) {
         $this->isAuthUserInSpecialLogUsers = false;
@@ -122,6 +138,8 @@ abstract class Log {
     }
 
     /**
+     * Returns the current device id.
+     *
      * @access public
      * @return string
      */
@@ -130,15 +148,20 @@ abstract class Log {
     }
 
     /**
+     * Sets the current device id.
+     *
      * @param string $value
      *
      * @access public
+     * @return void
      */
     public function SetDevid($value) {
         $this->devid = $value;
     }
 
     /**
+     * Returns the current PID (as string).
+     *
      * @access public
      * @return string
      */
@@ -147,15 +170,20 @@ abstract class Log {
     }
 
     /**
+     * Sets the current PID.
+     *
      * @param string $value
      *
      * @access public
+     * @return void
      */
     public function SetPidstr($value) {
         $this->pidstr = $value;
     }
 
     /**
+     * Indicates if special log users are known.
+     *
      * @access public
      * @return bool True if we do have to log some specific user. False otherwise.
      */
@@ -164,9 +192,11 @@ abstract class Log {
     }
 
     /**
+     * Indicates if the user is in the special log users.
+     *
      * @param string $user
      *
-     * @acces public
+     * @access public
      * @return bool
      */
     public function IsUserInSpecialLogUsers($user) {
@@ -181,6 +211,8 @@ abstract class Log {
     }
 
     /**
+     * Returns the current special log users array.
+     *
      * @access public
      * @return array
      */
@@ -189,29 +221,53 @@ abstract class Log {
     }
 
     /**
+     * Sets the current special log users array.
+     *
      * @param array $value
      *
      * @access public
+     * @return void
      */
     public function SetSpecialLogUsers(array $value) {
         $this->isUserInSpecialLogUsers = array(); // reset cache
         $this->specialLogUsers = $value;
     }
 
-    public function __construct() {
+    /**
+     * If called, the current user should get an extra log-file.
+     *
+     * If called until the user is authenticated (e.g. at the end of IBackend->Logon()) all
+     * messages logged until then will also be logged in the user file.
+     *
+     * @access public
+     * @return void
+     */
+    public function SpecialLogUser() {
+        $this->isAuthUserInSpecialLogUsers = true;
     }
 
     /**
+     * Logs a message with a given log level.
+     *
+     *
      * @param int $loglevel
      * @param string $message
+     *
+     * @access public
+     * @return void
      */
     public function Log($loglevel, $message) {
         if ($loglevel <= LOGLEVEL) {
             $this->Write($loglevel, $message);
         }
-        if ($loglevel <= LOGUSERLEVEL && $this->IsAuthUserInSpecialLogUsers()) {
-            if (RequestProcessor::isUserAuthenticated()) {
-                // something was logged before the user was authenticated, write this to the log
+        if ($loglevel <= LOGUSERLEVEL) {
+            // cache log messages for unauthenticated users
+            if (!RequestProcessor::isUserAuthenticated()) {
+                $this->unauthMessageCache[] = array($loglevel, $message);
+            }
+            // user is authenticated now
+            elseif ($this->IsAuthUserInSpecialLogUsers()) {
+                // something was logged before the user was authenticated and cached write it to the log
                 if (!empty($this->unauthMessageCache)) {
                     foreach ($this->unauthMessageCache as $authcache) {
                         $this->WriteForUser($authcache[0], $authcache[1]);
@@ -231,6 +287,9 @@ abstract class Log {
     /**
      * This function is used as an event for log implementer.
      * It happens when the ZLog static class is finished with the initialization of this instance.
+     *
+     * @access public
+     * @return void
      */
     public function AfterInitialize() {
     }
@@ -238,6 +297,9 @@ abstract class Log {
     /**
      * This function is used as an event for log implementer.
      * It happens when the a call to the Log function is finished.
+     *
+     * @access protected
+     * @return void
      */
     protected function afterLog($loglevel, $message) {
     }
@@ -271,20 +333,23 @@ abstract class Log {
     }
 
     /**
+     * Writes a log message to the general log.
+     *
      * @param int $loglevel
      * @param string $message
      *
-     * @access public
-     * @return null
+     * @access protected
+     * @return void
      */
     abstract protected function Write($loglevel, $message);
 
     /**
+     * Writes a log message to the user specific log.
      * @param int $loglevel
      * @param string $message
      *
      * @access public
-     * @return null
+     * @return void
      */
     abstract public function WriteForUser($loglevel, $message);
 }
\ No newline at end of file

src/lib/log/syslog.php

@@ -84,6 +84,14 @@ class Syslog extends Log {
         }
     }
 
+    /**
+     * Constructor.
+     * Sets configured values if no parameters are given.
+     *
+     * @param string $program_name
+     * @param string $host
+     * @param string $port
+     */
     public function __construct($program_name = null, $host = null, $port = null) {
         parent::__construct();
 
@@ -104,7 +112,6 @@ class Syslog extends Log {
      * @return string
      */
     protected function GenerateProgramName() {
-
         // @TODO Use another mechanism than debug_backtrace to determine to origin of the log
         $backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
         // Shift the "syslog.php" entry.
@@ -166,11 +173,19 @@ class Syslog extends Log {
         return $log;
     }
 
-
     //
     // Implementation of Log
     //
 
+    /**
+     * Writes a log message to the general log.
+     *
+     * @param int $loglevel
+     * @param string $message
+     *
+     * @access protected
+     * @return void
+     */
     protected function Write($loglevel, $message) {
         if ($this->GetHost() && $this->GetPort()) {
             $sock = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
@@ -191,6 +206,13 @@ class Syslog extends Log {
         }
     }
 
+    /**
+     * This function is used as an event for log implementer.
+     * It happens when the a call to the Log function is finished.
+     *
+     * @access public
+     * @return void
+     */
     public function WriteForUser($loglevel, $message) {
         $this->Write(LOGLEVEL_DEBUG, $message); // Always pass the logleveldebug so it uses syslog level LOG_DEBUG
     }

src/lib/request/requestprocessor.php

@@ -117,7 +117,7 @@ abstract class RequestProcessor {
         }
 
         // also log WBXML in happy case
-        if (@constant('WBXML_DEBUG') === true) {
+        if (ZLog::IsWbxmlDebugEnabled()) {
             ZLog::Write(LOGLEVEL_WBXML, "WBXML-IN : ". Request::GetInputAsBase64(), false);
         }
     }

src/lib/wbxml/wbxmldecoder.php

@@ -85,7 +85,7 @@ class WBXMLDecoder extends WBXMLDefs {
      * @access public
      */
     public function __construct($input) {
-        $this->log = defined('WBXML_DEBUG') && WBXML_DEBUG;
+        $this->log = ZLog::IsWbxmlDebugEnabled();
 
         $this->in = $input;
 

src/lib/wbxml/wbxmlencoder.php

@@ -44,7 +44,7 @@ class WBXMLEncoder extends WBXMLDefs {
     private $bodyparts;
 
     public function __construct($output, $multipart = false) {
-        $this->log = @constant('WBXML_DEBUG') === true;
+        $this->log = ZLog::IsWbxmlDebugEnabled();
 
         $this->_out = $output;
 

tools/dev/printwbxml.php

@@ -69,6 +69,10 @@ class ZLog {
             }
         }
     }
+
+    static public function IsWbxmlDebugEnabled() {
+        return true;
+    }
 }
 
 // setup