Trap PHP errors while this object is alive, so they can be accessed and included in exceptions or other types of logging. For example, if you have code like this:

$res = proc_open(...);

There is no easy way to throw an informative exception if the proc_open() fails. In some cases you may be able to use error_get_last(), but this is unreliable (if proc_open() fails because disable_functions is set, it does not capture the error) and can not capture more than one error.

You can trap errors while executing this code instead:

$trap = new PhutilErrorTrap();
  $res = proc_open(...);
  $err = $trap->getErrorsAsString();
$trap->destroy();

if (!$res) {
  throw new Exception('proc_open() failed: '.$err);
}

Some notes on traps:

• Traps catch all errors, including those silenced by @.
• Traps do not prevent errors from reaching other standard handlers. You can use @ to keep errors out of the logs while still trapping them.
• Traps capture all errors until they are explicitly destroyed. This means that you should not create long-lived traps, or they may consume unbounded amounts of memory to hold the error log.