Logging

Synopsis

The Daemon provides a simple and robust logging mechanism that includes 4 methods for logging various types of messages. And a LogTrait to allow other classes to use the daemon log without any special setup. All logging methods accept a variable list of arguments and are processed by sprintf. So all messages can use placeholders, like %s or %d or anything else sprintf supports.

There is 1 more method output that is responsible for outputting your messages to the screen (or potentially other places). This method is only called if Daemon::isVerbose() is true.

Methods

• log(string $msg, $args[]...)
  Log an informational message.
  The event DaemonEvents::ON_LOG will be triggered. If any listening handlers stop propagation on the LogEvent then no message will be logged.

• error(string|Exception $msg, $args[]...)
  Log an error message. The first parameter $msg can be a string or Exception. If an Exception is given then the full stack trace of the exception is appended to the message.
  The event DaemonEvents::ON_ERROR will be triggered. If any listening handlers stop propagation on the ErrorEvent then no message will be logged. Uses log() to do the actual output.

• fatalError(string|Exception $msg, $args[]...)
  A special method that will log an error just like error() does, but will also trigger a restart of the daemon if enabled and certain criteria is met.
  Uses error() to do the actual output. No matter what, the daemon will exit(1) when you call this method. So only call it for REAL fatal errors!

• debug([int $level = 1], string $msg, $args[]...)
debug($msg, $args[]...)
  Log a debug message. This method has an extra parameter that allows you to set the level of the debug message. By default the level is 1. If you do not specify a level then the first parameter can be the $msg instead. If you do specify the $level it has to be an integer (1) and not a string representing an integer ("1"). Uses log() to do the actual output.

• output(string $msg) By default, this method accepts a string and will output it to STDERR. The main log() method will call this function to echo the $msg being logged. You can call Daemon::setOutput($output) to change the destination of where output will go. By default output will go to STDERR. But you can change it to one of the following:

  • null - STDERR
  • callable - Any callable. The function will receive the string as a parameter.
  • resource - A stream resource (eg: handle from fopen) or a file handle constant: STDERR, STDOUT.
  • string - A filename. The file will be opened and all messages will be written to the file.

Features

The logging routines can automatically detect when the log file is rotated, renamed or deleted from an external process. When this occurs the log will be re-opened and logging will continue w/o any hiccups! Currently, Daemon::$advancedLogChecks must be enabled for this feature to work.

Log Trait

The php-daemon library includes a LogTrait trait that allows any class to use and be able to easily use the above methods (except fatalError()) to log to the daemon. This trait also includes a special method setLogArguments($args[], $type = 'log') that allows your class to override how the final message is logged. By default the LogTrait will prepend the base class name in front of all messages.

For example:

class MyClass {
  use Lifo\Daemon\LogTrait;
  public function __construct() {
    $this->debug("instance was created!");
  } 
}