Page MenuHomePhabricator
Diviner libphutil Tech Docs PhutilDeferredLog

final class PhutilDeferredLog
libphutil Technical Documentation (Filesystem)

Object that writes to a logfile when it is destroyed. This allows you to add more data to the log as execution unfolds, while still ensuring a write in normal circumstances (see below for discussion of cases where writes may not occur).

Create the object with a logfile and format:

$log = new PhutilDeferredLog('/path/to/access.log', "[%T]\t%u");

Update the log with information as it becomes available:

$log->setData(
  array(
    'T' => date('c'),
    'u' => $username,
 ));

The log will be appended when the object's destructor is called, or when you invoke write(). Note that programs can exit without invoking object destructors (e.g., in the case of an unhandled exception, memory exhaustion, or SIGKILL) so writes are not guaranteed. You can call write() to force an explicit write to disk before the destructor is called.

Log variables will be written with bytes 0x00-0x1F, 0x7F-0xFF, and backslash escaped using C-style escaping. Since this range includes tab, you can use tabs as field separators to ensure the file format is easily parsable. In PHP, you can decode this encoding with stripcslashes.

If a variable is included in the log format but a value is never provided with setData(), it will be written as "-".

Tasks

Logging

  • public function __construct($file, $format) — Create a new log entry, which will be written later. The format string should use "%x"-style placeholders to represent data which will be added later:
  • public function setData($map) — Add data to the log. Provide a map of variables to replace in the format string. For example, if you use a format string like:
  • public function getData($key, $default) — Get existing log data.
  • public function setFile($file) — Set the path where the log will be written. You can pass `null` to prevent the log from writing.

Writing the Log

  • public function __destruct() — When the log object is destroyed, it writes if it hasn't written yet.
  • public function write() — Write the log explicitly, if it hasn't been written yet. Normally you do not need to call this method; it will be called when the log object is destroyed. However, you can explicitly force the write earlier by calling this method.

Internals

No methods for this task.

Other Methods

  • public function getFile()
  • public function setFailQuietly($fail_quietly) — Set quiet (logged) failure, instead of the default loud (exception) failure. Throwing exceptions from destructors which exit at the end of a request can result in difficult-to-debug behavior.

internals

  • private function format() — Format the log string, replacing "%x" variables with values.

Methods

public function __construct($file, $format)

Create a new log entry, which will be written later. The format string should use "%x"-style placeholders to represent data which will be added later:

$log = new PhutilDeferredLog('/some/file.log', '[%T] %u');
Parameters
string|null$fileThe file the entry should be written to, or null to create a log object which does not write anywhere.
string$formatThe log entry format.
Return
this//Implicit.//

public function setData($map)

Add data to the log. Provide a map of variables to replace in the format string. For example, if you use a format string like:

"[%T]\t%u"

...you might add data like this:

$log->setData(
  array(
    'T' => date('c'),
    'u' => $username,
  ));

When the log is written, the "%T" and "%u" variables will be replaced with the values you provide.

Parameters
dict$mapMap of variables to values.
Return
this

public function getData($key, $default)

Get existing log data.

Parameters
string$keyLog data key.
wild$defaultDefault to return if data does not exist.
Return
wildData, or default if data does not exist.

public function setFile($file)

Set the path where the log will be written. You can pass null to prevent the log from writing.

NOTE: You can not change the file after the log writes.
Parameters
string|null$fileFile where the entry should be written to, or null to prevent writes.
Return
this

public function getFile()

This method is not documented.
Return
wild

public function setFailQuietly($fail_quietly)

Set quiet (logged) failure, instead of the default loud (exception) failure. Throwing exceptions from destructors which exit at the end of a request can result in difficult-to-debug behavior.

Parameters
$fail_quietly
Return
wild

public function __destruct()

When the log object is destroyed, it writes if it hasn't written yet.

Return
wild

public function write()

Write the log explicitly, if it hasn't been written yet. Normally you do not need to call this method; it will be called when the log object is destroyed. However, you can explicitly force the write earlier by calling this method.

A log object will never write more than once, so it is safe to call this method even if the object's destructor later runs.

Return
this

private function format()

Format the log string, replacing "%x" variables with values.

Return
stringFinalized, log string for writing to disk.
Defined
src/filesystem/PhutilDeferredLog.php:39
Phabricator · Built by Phacility