[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Wrapper around backtraces providing utility methods.
   4   *
   5   * Copyright 1999-2014 Horde LLC (http://www.horde.org/)
   6   *
   7   * @category   Horde
   8   * @package    Support
   9   * @license    http://www.horde.org/licenses/bsd
  10   */
  11  class Horde_Support_Backtrace
  12  {
  13      /**
  14       * Backtrace.
  15       *
  16       * @var array
  17       */
  18      public $backtrace;
  19  
  20      /**
  21       * Constructor.
  22       *
  23       * @param Exception|array $backtrace  The backtrace source. Either an
  24       *                                    exception or an existing backtrace.
  25       *                                    Defaults to the current stack.
  26       */
  27      public function __construct($backtrace = null)
  28      {
  29          if ($backtrace instanceof Exception) {
  30              $this->createFromException($backtrace);
  31          } elseif ($backtrace) {
  32              $this->createFromDebugBacktrace($backtrace);
  33          } else {
  34              $this->createFromDebugBacktrace(debug_backtrace(), 1);
  35          }
  36      }
  37  
  38      /**
  39       * Wraps the result of debug_backtrace().
  40       *
  41       * By specifying a non-zero $nestingLevel, levels of the backtrace can be
  42       * ignored. For instance, when Horde_Support_Backtrace creates a backtrace
  43       * for you, it ignores the Horde_Backtrace constructor in the wrapped
  44       * trace.
  45       *
  46       * @param array $backtrace       The debug_backtrace() result.
  47       * @param integer $nestingLevel  The number of levels of the backtrace to
  48       *                               ignore.
  49       */
  50      public function createFromDebugBacktrace($backtrace, $nestingLevel = 0)
  51      {
  52          while ($nestingLevel > 0) {
  53              array_shift($backtrace);
  54              --$nestingLevel;
  55          }
  56  
  57          $this->backtrace = $backtrace;
  58      }
  59  
  60      /**
  61       * Wraps an Exception object's backtrace.
  62       *
  63       * @param Exception $e  The exception to wrap.
  64       */
  65      public function createFromException(Exception $e)
  66      {
  67          $this->backtrace = $e->getTrace();
  68          if ($previous = $e->getPrevious()) {
  69              $backtrace = new self($previous);
  70              $this->backtrace = array_merge($backtrace->backtrace,
  71                                             $this->backtrace);
  72          }
  73      }
  74  
  75      /**
  76       * Returns the nesting level (number of calls deep) of the current context.
  77       *
  78       * @return integer  Nesting level.
  79       */
  80      public function getNestingLevel()
  81      {
  82          return count($this->backtrace);
  83      }
  84  
  85      /**
  86       * Returns the context at a specific nesting level.
  87       *
  88       * @param integer $nestingLevel  0 == current level, 1 == caller, and so on
  89       *
  90       * @return array  The requested context.
  91       */
  92      public function getContext($nestingLevel)
  93      {
  94          if (!isset($this->backtrace[$nestingLevel])) {
  95              throw new Horde_Exception('Unknown nesting level');
  96          }
  97          return $this->backtrace[$nestingLevel];
  98      }
  99  
 100      /**
 101       * Returns details about the routine where the exception occurred.
 102       *
 103       * @return array $caller
 104       */
 105      public function getCurrentContext()
 106      {
 107          return $this->getContext(0);
 108      }
 109  
 110      /**
 111       * Returns details about the caller of the routine where the exception
 112       * occurred.
 113       *
 114       * @return array $caller
 115       */
 116      public function getCallingContext()
 117      {
 118          return $this->getContext(1);
 119      }
 120  
 121      /**
 122       * Returns a simple, human-readable list of the complete backtrace.
 123       *
 124       * @return string  The backtrace map.
 125       */
 126      public function __toString()
 127      {
 128          $count = count($this->backtrace);
 129          $pad = strlen($count);
 130          $map = '';
 131          for ($i = $count - 1; $i >= 0; $i--) {
 132              $map .= str_pad($count - $i, $pad, ' ', STR_PAD_LEFT) . '. ';
 133              if (isset($this->backtrace[$i]['class'])) {
 134                  $map .= $this->backtrace[$i]['class']
 135                      . $this->backtrace[$i]['type'];
 136              }
 137              $map .= $this->backtrace[$i]['function'] . '()';
 138              if (isset($this->backtrace[$i]['file'])) {
 139                  $map .= ' ' . $this->backtrace[$i]['file']
 140                      . ':' . $this->backtrace[$i]['line'];
 141              }
 142              $map .= "\n";
 143          }
 144          return $map;
 145      }
 146  }