* trace

- can pass trace as argument (prev only as a meta value) - new meta option : inclInternal (default: `false`) * groupEnd - can specify "label" via meta value (defaults to "return") * most methods now recognize "level" meta value (not just group) * backed Enums - incl backing value in classname's title attr * refactor StatementInfo - adding to log is now handled separately via new StatementInfoLogger
bkdotcom · Jan 11, 2025 · f5bbf6f · f5bbf6f
1 parent 672691d
commit f5bbf6f
Show file tree

Hide file tree

Showing 66 changed files with 750 additions and 583 deletions.
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
@@ -135,6 +135,7 @@
         <exclude name="Squiz.Commenting.LongConditionClosingComment.Missing" />
 
         <!-- PostStatementComment -->
+        <exclude name="Squiz.Commenting.PostStatementComment.AnnotationFound" />
         <exclude name="Squiz.Commenting.PostStatementComment.Found" />
 
         <!-- VariableComment -->

diff --git a/src/Backtrace/Backtrace.php b/src/Backtrace/Backtrace.php
@@ -32,6 +32,7 @@ class Backtrace
 {
     const INCL_ARGS = 1;
     const INCL_OBJECT = 2;
+    const INCL_INTERNAL = 4; // whether to keep "internal" frames
 
     /** @var array */
     protected static $callerInfoDefault = array(
@@ -75,17 +76,20 @@ public static function addInternalClass($classes, $level = 0)
     public static function get($options = 0, $limit = 0, $exception = null)
     {
         $debugBacktraceOpts = self::translateOptions($options);
-        $limit = $limit ?: null;
+        $sliceLimit = $limit ?: null;
+        $backtraceLimit = $limit > 0 ? $limit + 2 : 0;
         $trace = $exception
             ? self::getExceptionTrace($exception)
             : (\array_reverse(Xdebug::getFunctionStack() ?: [])
-                ?: \debug_backtrace($debugBacktraceOpts, $limit > 0 ? $limit + 2 : 0));
+                ?: \debug_backtrace($debugBacktraceOpts, $backtraceLimit));
         $trace = Normalizer::normalize($trace);
-        $trace = SkipInternal::removeInternalFrames($trace);
+        if (($options & self::INCL_INTERNAL) !== self::INCL_INTERNAL) {
+            $trace = SkipInternal::removeInternalFrames($trace);
+        }
         // keep the calling file & line, but toss the called function (what initiated trace)
         unset($trace[0]['function']);
         unset($trace[\count($trace) - 1]['function']);  // remove "{main}"
-        $trace = \array_slice($trace, 0, $limit);
+        $trace = \array_slice($trace, 0, $sliceLimit);
         $keysRemove = \array_filter(array(
             'args' => ($options & self::INCL_ARGS) !== self::INCL_ARGS,
             'object' => ($options & self::INCL_OBJECT) !== self::INCL_OBJECT,

diff --git a/src/Container/Container.php b/src/Container/Container.php
@@ -112,7 +112,7 @@ public function __construct($values = array(), $cfg = array())
      *  - take the value as its first argument and the container as its second argument
      *  - return the modified value
      *
-     * @param string   $id       The unique identifier for the object
+     * @param string   $name     The unique identifier for the object
      * @param callable $callable A service definition to extend the original
      *
      * @return void
@@ -413,7 +413,7 @@ private function assertExists($name)
     /**
      * Assert that the identifier exists
      *
-     * @param string $name Identifier of entry to check
+     * @param mixed $val Value to check
      *
      * @return void
      *
@@ -444,7 +444,7 @@ protected static function getDebugType($value)
     }
 
     /**
-     * Undocumented function
+     * Called when service or factory is invoked
      *
      * @param string $name  The service or factory name
      * @param mixed  $value The value returned by the definition

diff --git a/src/CurlHttpMessage/CurlReqResOptions.php b/src/CurlHttpMessage/CurlReqResOptions.php
@@ -204,7 +204,7 @@ private function requestHeadersToHeaders(array $requestHeaders)
 
             if ($nameLower === 'accept-encoding') {
                 // CURLOPT_ENCODING - Available as of cURL 7.10 and deprecated as of cURL 7.21.6.
-                $this->curlOptions[CURLOPT_ACCEPT_ENCODING] = implode(', ', $values); // available as of cURL 7.21.6.
+                $this->curlOptions[CURLOPT_ACCEPT_ENCODING] = \implode(', ', $values); // available as of cURL 7.21.6.
                 return;
             }
 

diff --git a/src/Debug/Abstraction/Object/Abstraction.php b/src/Debug/Abstraction/Object/Abstraction.php
@@ -125,19 +125,6 @@ public function getInheritedValues()
         return $values;
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    public function getValues()
-    {
-        $return = \array_replace_recursive(
-            $this->getInheritedValues(),
-            $this->values
-        );
-        \ksort($return, SORT_NATURAL);
-        return $return;
-    }
-
     /**
      * Get instance related values
      *
@@ -151,6 +138,19 @@ public function getInstanceValues()
         );
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function getValues()
+    {
+        $return = \array_replace_recursive(
+            $this->getInheritedValues(),
+            $this->values
+        );
+        \ksort($return, SORT_NATURAL);
+        return $return;
+    }
+
     /**
      * Sorts constant/property/method array by visibility or name
      *

diff --git a/src/Debug/Abstraction/Object/MethodParams.php b/src/Debug/Abstraction/Object/MethodParams.php
@@ -258,8 +258,8 @@ private function phpDocConstant($defaultValue, $className, array $matches)
     /**
      * Get PhpDoc param info
      *
-     * @param string $name               param name
-     * @param array  $phpDocParamsByName [description]
+     * @param string $name               Param name
+     * @param array  $phpDocParamsByName Params defined in PhpDoc
      *
      * @return array
      */

diff --git a/src/Debug/Abstraction/Type.php b/src/Debug/Abstraction/Type.php
@@ -31,7 +31,7 @@ class Type
     const TYPE_RESOURCE = 'resource';
     const TYPE_STRING = 'string';
     const TYPE_CONST = 'const'; // non-native type (Abstraction: we store name and value)
-                                // deprecated (use TYPE_IDENTIFIER)
+                                //   deprecated (use TYPE_IDENTIFIER)
     const TYPE_IDENTIFIER = 'identifier'; // const, className, method, property
                                             // value: identifier
                                             // backedValue: underlying const or property value

diff --git a/src/Debug/Collector/DatabaseTrait.php b/src/Debug/Collector/DatabaseTrait.php
@@ -14,6 +14,7 @@
 
 use bdk\Debug;
 use bdk\Debug\Collector\StatementInfo;
+use bdk\Debug\Collector\StatementInfoLogger;
 use Pdo as PdoBase;
 
 /**
@@ -27,6 +28,12 @@ trait DatabaseTrait
     /** @var string */
     protected $icon = ':database:';
 
+    /** @var StatementInfoLogger */
+    protected $statementInfoLogger;
+
+    /** @var Debug */
+    private $debug;
+
     /**
      * Logs StatementInfo
      *
@@ -37,7 +44,7 @@ trait DatabaseTrait
     public function addStatementInfo(StatementInfo $info)
     {
         $this->loggedStatements[] = $info;
-        $info->appendLog($this->debug);
+        $this->statementInfoLogger->log($info);
     }
 
     /**
@@ -77,6 +84,16 @@ public function getLoggedStatements()
         return $this->loggedStatements;
     }
 
+    /**
+     * Get StatementInfoLogger
+     *
+     * @return StatementInfoLogger
+     */
+    public function getStatementInfoLogger()
+    {
+        return $this->statementInfoLogger;
+    }
+
     /**
      * Extend me to return the current database name
      *
@@ -107,7 +124,7 @@ private function logRuntime(Debug $debug)
         if ($serverInfo) {
             $debug->log('server info', $serverInfo);
         }
-        if ($this->prettified() === false) {
+        if ($this->statementInfoLogger->prettified() === false) {
             $debug->info('require jdorn/sql-formatter to prettify logged sql statements');
         }
     }
@@ -152,6 +169,8 @@ protected function meta(array $values = array())
     /**
      * Return server information
      *
+     * @param PdoBase $pdo Pdo instance
+     *
      * @return array
      *
      * @SuppressWarnings(PHPMD.UnusedPrivateMethod) -> called via DatabaseTrait
@@ -175,32 +194,34 @@ protected function pdoServerInfo(PdoBase $pdo)
     }
 
     /**
-     * Were attempts to prettify successful?
+     * Extend me to return database server information
      *
-     * @return bool
+     * @return array
      */
-    private function prettified()
+    protected function serverInfo()
     {
-        $falseCount = 0;
-        foreach ($this->loggedStatements as $info) {
-            $prettified = $info->prettified;
-            if ($prettified === true) {
-                return true;
-            }
-            if ($prettified === false) {
-                $falseCount++;
-            }
-        }
-        return $falseCount === 0;
+        return array();
     }
 
     /**
-     * Extend me to return database server information
+     * Initialize Debug and StatementInfoLogger
      *
-     * @return array
+     * @param Debug|null $debug       (optional) Specify PHPDebugConsole instance
+     *                                  if not passed, will create MySqli channel on singleton instance
+     *                                  if root channel is specified, will create a MySqli channel
+     * @param string     $channelName Channel name to use for debug instance
+     *
+     * @return void
      */
-    protected function serverInfo()
+    protected function traitInit($debug, $channelName = 'SQL')
     {
-        return array();
+        if (!$debug) {
+            $debug = Debug::getChannel($channelName, array('channelIcon' => $this->icon));
+        } elseif ($debug === $debug->rootInstance) {
+            $debug = $debug->getChannel($channelName, array('channelIcon' => $this->icon));
+        }
+        $this->debug = $debug;
+        $this->statementInfoLogger = new StatementInfoLogger($debug);
+        $debug->addPlugin($debug->pluginHighlight);
     }
 }
diff --git a/src/Debug/Collector/Doctrine/Connection.php b/src/Debug/Collector/Doctrine/Connection.php
@@ -20,9 +20,6 @@ class Connection extends AbstractConnectionMiddleware
 {
     use DatabaseTrait;
 
-    /** @var Debug */
-    protected $debug;
-
     /** @var array */
     private $params = array();
 
@@ -42,9 +39,8 @@ public function __construct(
     {
         parent::__construct($connection);
         $this->params = $params;
-        $this->debug = $debug;
+        $this->traitInit($debug);
         $this->debug->eventManager->subscribe(Debug::EVENT_OUTPUT, [$this, 'onDebugOutput'], 1);
-        $this->debug->addPlugin($debug->pluginHighlight);
     }
 
     /**

diff --git a/src/Debug/Collector/Doctrine/Statement.php b/src/Debug/Collector/Doctrine/Statement.php
@@ -59,11 +59,7 @@ public function bindValue($param, $value, $type = ParameterType::STRING): void
      */
     public function execute($params = null): ResultInterface
     {
-        $info = new StatementInfo(
-            $this->sql,
-            $this->params,
-            $this->types
-        );
+        $info = new StatementInfo($this->sql, $this->params, $this->types);
         $result  = parent::execute();
 
         $exception = null;

diff --git a/src/Debug/Collector/DoctrineLogger.php b/src/Debug/Collector/DoctrineLogger.php
@@ -38,9 +38,6 @@ class DoctrineLogger implements SQLLoggerInterface
     /** @var Connection */
     private $connection;
 
-    /** @var Debug */
-    private $debug;
-
     /**
      * Constructor
      *
@@ -54,16 +51,9 @@ public function __construct($connection = null, $debug = null)
     {
         \bdk\Debug\Utility::assertType($connection, 'Doctrine\DBAL\Connection');
         \bdk\Debug\Utility::assertType($debug, 'bdk\Debug');
-
-        if (!$debug) {
-            $debug = Debug::getChannel('Doctrine', array('channelIcon' => $this->icon));
-        } elseif ($debug === $debug->rootInstance) {
-            $debug = $debug->getChannel('Doctrine', array('channelIcon' => $this->icon));
-        }
+        $this->traitInit($debug, 'Doctrine');
         $this->connection = $connection;
-        $this->debug = $debug;
         $this->debug->eventManager->subscribe(Debug::EVENT_OUTPUT, [$this, 'onDebugOutput'], 1);
-        $this->debug->addPlugin($debug->pluginHighlight);
     }
 
     /**
@@ -105,7 +95,6 @@ public function stopQuery()
     {
         $statementInfo = $this->statementInfo;
         $statementInfo->end();
-        $statementInfo->appendLog($this->debug);
-        $this->loggedStatements[] = $statementInfo;
+        $this->addStatementInfo($statementInfo);
     }
 }
diff --git a/src/Debug/Collector/MySqli.php b/src/Debug/Collector/MySqli.php
@@ -41,9 +41,6 @@ class MySqli extends mysqliBase
     /** @var list<string> */
     protected $savePoints = array();
 
-    /** @var Debug */
-    private $debug;
-
     /**
      * Constructor
      *
@@ -66,14 +63,8 @@ public function __construct($host = null, $username = null, $passwd = null, $dbn
         $this->doConstruct(\func_num_args()
             ? \array_slice(\func_get_args(), 0, 6)
             : array());
-        if (!$debug) {
-            $debug = Debug::getChannel('MySqli', array('channelIcon' => $this->icon));
-        } elseif ($debug === $debug->rootInstance) {
-            $debug = $debug->getChannel('MySqli', array('channelIcon' => $this->icon));
-        }
-        $this->debug = $debug;
-        $debug->eventManager->subscribe(Debug::EVENT_OUTPUT, [$this, 'onDebugOutput'], 1);
-        $debug->addPlugin($debug->pluginHighlight);
+        $this->traitInit($debug, 'MySqli');
+        $this->debug->eventManager->subscribe(Debug::EVENT_OUTPUT, [$this, 'onDebugOutput'], 1);
     }
 
     /**

diff --git a/src/Debug/Collector/Pdo.php b/src/Debug/Collector/Pdo.php
@@ -28,9 +28,6 @@ class Pdo extends PdoBase
     use CompatTrait;
     use DatabaseTrait;
 
-    /** @var Debug */
-    private $debug;
-
     /** @var PdoBase */
     protected $pdo;
 
@@ -47,17 +44,10 @@ class Pdo extends PdoBase
     public function __construct(PdoBase $pdo, $debug = null)
     {
         \bdk\Debug\Utility::assertType($debug, 'bdk\Debug');
-
-        if (!$debug) {
-            $debug = Debug::getChannel('PDO', array('channelIcon' => $this->icon));
-        } elseif ($debug === $debug->rootInstance) {
-            $debug = $debug->getChannel('PDO', array('channelIcon' => $this->icon));
-        }
+        $this->traitInit($debug, 'PDO');
         $this->pdo = $pdo;
-        $this->debug = $debug;
         $this->setAttribute(PdoBase::ATTR_STATEMENT_CLASS, ['bdk\Debug\Collector\Pdo\Statement', [$this]]);
-        $debug->eventManager->subscribe(Debug::EVENT_OUTPUT, [$this, 'onDebugOutput'], 1);
-        $debug->addPlugin($debug->pluginHighlight);
+        $this->debug->eventManager->subscribe(Debug::EVENT_OUTPUT, [$this, 'onDebugOutput'], 1);
     }
 
     /**