Diviner Arcanist Tech Docs PhutilDeferredLog

final class PhutilDeferredLog
Arcanist Technical Documentation ()

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 __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
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 __get($name)
Inherited

This method is not documented.

Parameters

$name

Return

wild

public function __set($name, $value)
Inherited

This method is not documented.

Parameters

	$name
	$value

Return

wild

public function current()
Inherited

This method is not documented.

Return

wild

public function key()
Inherited

This method is not documented.

Return

wild

public function next()
Inherited

This method is not documented.

Return

wild

public function rewind()
Inherited

This method is not documented.

Return

wild

public function valid()
Inherited

This method is not documented.

Return

wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.

Return

wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters

string	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

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	$file	The file the entry should be written to, or null to create a log object which does not write anywhere.
string	$format	The 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

$map

Map of variables to values.

Return

this

public function getData($key, $default)

Get existing log data.

Parameters

string	$key	Log data key.
wild	$default	Default to return if data does not exist.

Return

wild	Data, 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

$file

File 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

string

Finalized, log string for writing to disk.

Defined: src/filesystem/PhutilDeferredLog.php:39
Extends: Phobject

final class PhutilDeferredLogArcanist Technical Documentation ()

Tasks

Logging

Writing the Log

Internals

Other Methods

internals

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public function __construct($file, $format)

public function setData($map)

public function getData($key, $default)

public function setFile($file)

public function getFile()

public function setFailQuietly($fail_quietly)

public function __destruct()

public function write()

private function format()

final class PhutilDeferredLog
Arcanist Technical Documentation ()

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited