File Manager

Editing File: /home/ubuntu/code_review/arcanist/src/filesystem/PhutilDeferredLog.php

<?php

/**
 * 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 @{method: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 @{method: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 @{method:setData}, it will be written as "-".
 *
 * @task log        Logging
 * @task write      Writing the Log
 * @task internal   Internals
 */
final class PhutilDeferredLog extends Phobject {

private $file;
  private $format;
  private $data;
  private $didWrite;
  private $failQuietly;

/* -(  Logging  )------------------------------------------------------------ */

/**
   * 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');
   *
   * @param string|null The file the entry should be written to, or null to
   *                    create a log object which does not write anywhere.
   * @param string      The log entry format.
   * @task log
   */
  public function __construct($file, $format) {
    $this->file = $file;
    $this->format = $format;
    $this->data = array();
    $this->didWrite = false;
  }

/**
   * 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.
   *
   * @param dict  Map of variables to values.
   * @return this
   * @task log
   */
  public function setData(array $map) {
    $this->data = $map + $this->data;
    return $this;
  }

/**
   * Get existing log data.
   *
   * @param   string  Log data key.
   * @param   wild    Default to return if data does not exist.
   * @return  wild    Data, or default if data does not exist.
   * @task log
   */
  public function getData($key, $default = null) {
    return idx($this->data, $key, $default);
  }

/**
   * 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.
   *
   * @param string|null File where the entry should be written to, or null to
   *                    prevent writes.
   * @return this
   * @task log
   */
  public function setFile($file) {
    if ($this->didWrite) {
      throw new Exception(
        pht('You can not change the logfile after a write has occurred!'));
    }
    $this->file = $file;
    return $this;
  }

public function getFile() {
    return $this->file;
  }

/**
   * 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.
   */
  public function setFailQuietly($fail_quietly) {
    $this->failQuietly = $fail_quietly;
    return $this;
  }

/* -(  Writing the Log  )---------------------------------------------------- */

/**
   * When the log object is destroyed, it writes if it hasn't written yet.
   * @task write
   */
  public function __destruct() {
    $this->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
   * @task write
   */
  public function write() {
    if ($this->didWrite) {
      return $this;
    }

// Even if we aren't going to write, format the line to catch any errors
    // and invoke possible __toString() calls.
    $line = $this->format();

try {
      if ($this->file !== null) {
        $dir = dirname($this->file);
        if (!Filesystem::pathExists($dir)) {
          Filesystem::createDirectory($dir, 0755, true);
        }

$ok = @file_put_contents(
          $this->file,
          $line,
          FILE_APPEND | LOCK_EX);

if ($ok === false) {
          throw new Exception(
            pht(
              'Unable to write to logfile "%s"!',
              $this->file));
        }
      }
    } catch (Exception $ex) {
      if ($this->failQuietly) {
        phlog($ex);
      } else {
        throw $ex;
      }
    }

$this->didWrite = true;
    return $this;
  }

/* -(  Internals  )---------------------------------------------------------- */

/**
   * Format the log string, replacing "%x" variables with values.
   *
   * @return string Finalized, log string for writing to disk.
   * @task internals
   */
  private function format() {

// Always convert '%%' to literal '%'.
    $map = array('%' => '%') + $this->data;

$result = '';
    $saw_percent = false;
    foreach (phutil_utf8v($this->format) as $c) {
      if ($saw_percent) {
        $saw_percent = false;
        if (array_key_exists($c, $map)) {
          $result .= phutil_encode_log($map[$c]);
        } else {
          $result .= '-';
        }
      } else if ($c == '%') {
        $saw_percent = true;
      } else {
        $result .= $c;
      }
    }

return rtrim($result)."\n";
  }

}

Back to Directory File Manager