type-hints / static analysis (primary focus on HttpMessage)

Javascript fixes
Update phpDoc types list

src/Backtrace/Backtrace.php

@@ -4,7 +4,7 @@
  * @package   Backtrace
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2020-2023 Brad Kent
+ * @copyright 2020-2024 Brad Kent
  * @version   v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
@@ -16,7 +16,9 @@
 use bdk\Backtrace\SkipInternal;
 use bdk\Backtrace\Xdebug;
 use Exception;
+use InvalidArgumentException;
 use ParseError;
+use Throwable;
 
 /**
  * Utility for getting backtrace
@@ -31,6 +33,7 @@ class Backtrace
     const INCL_ARGS = 1;
     const INCL_OBJECT = 2;
 
+    /** @var array */
     protected static $callerInfoDefault = array(
         'args' => array(),
         'class' => null,         // where the method is defined
@@ -67,7 +70,7 @@ public static function addInternalClass($classes, $level = 0)
      * @param int                   $limit     limit the number of stack frames returned.
      * @param \Exception|\Throwable $exception (optional) Exception from which to get backtrace
      *
-     * @return array
+     * @return array[]
      */
     public static function get($options = 0, $limit = 0, $exception = null)
     {
@@ -76,7 +79,7 @@ public static function get($options = 0, $limit = 0, $exception = null)
         $trace = $exception
             ? self::getExceptionTrace($exception)
             : (\array_reverse(Xdebug::getFunctionStack() ?: array())
-                ?: \debug_backtrace($debugBacktraceOpts, $limit ? $limit + 2 : 0));
+                ?: \debug_backtrace($debugBacktraceOpts, $limit > 0 ? $limit + 2 : 0));
         $trace = Normalizer::normalize($trace);
         $trace = SkipInternal::removeInternalFrames($trace);
         // keep the calling file & line, but toss the called function (what initiated trace)
@@ -138,7 +141,7 @@ public static function getCallerInfo($offset = 0, $options = 0)
      * @param array $backtrace backtrace frames
      * @param int   $length    number of lines to include
      *
-     * @return array backtrace
+     * @return array[] backtrace
      */
     public static function addContext(array $backtrace, $length = 19)
     {
@@ -166,7 +169,7 @@ public static function getFileLines($file, $start = null, $length = null)
      *
      * @param array $backtrace backtrace
      *
-     * @return array
+     * @return array[]
      */
     private static function callerInfoBuild(array $backtrace)
     {
@@ -270,7 +273,7 @@ private static function parseFunction($function)
     /**
      * Convert our additive options to PHP's options
      *
-     * @param int $options bitmask options
+     * @param int|null $options bitmask options
      *
      * @return int
      */

src/Backtrace/Context.php

@@ -4,7 +4,7 @@
  * @package   Backtrace
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2020-2023 Brad Kent
+ * @copyright 2020-2024 Brad Kent
  * @version   v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
@@ -55,9 +55,9 @@ public static function add(array $backtrace, $length = 19)
      *
      * Returns array of lineNumber => line
      *
-     * @param string $file   filepath
-     * @param int    $start  line to start on (1 = first line)
-     * @param int    $length number of lines to return
+     * @param string   $file   filepath
+     * @param int|null $start  line to start on (1 = first line)
+     * @param int|null $length number of lines to return
      *
      * @return array|false false if file doesn't exist
      */
@@ -116,9 +116,9 @@ private static function findEvalCode(array $backtrace, $index)
      *
      * Essentially array_slice but one-based vs zero-based
      *
-     * @param array $lines  lines of code
-     * @param int   $start  line to start on (1 = first line)
-     * @param int   $length number of lines to return
+     * @param array    $lines  lines of code
+     * @param int|null $start  line to start on (1 = first line)
+     * @param int|null $length number of lines to return
      *
      * @return array
      */

src/Backtrace/Normalizer.php

@@ -4,7 +4,7 @@
  * @package   Backtrace
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2020-2023 Brad Kent
+ * @copyright 2020-2024 Brad Kent
  * @version   v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
@@ -16,8 +16,10 @@
  */
 class Normalizer
 {
+    /** @var array */
     private static $backtraceTemp = array();
 
+    /** @var array */
     private static $frameDefault = array(
         'args' => array(),
         'evalLine' => null,

src/Backtrace/SkipInternal.php

@@ -4,7 +4,7 @@
  * @package   Backtrace
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2020-2023 Brad Kent
+ * @copyright 2020-2024 Brad Kent
  * @version   v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
@@ -54,7 +54,10 @@ class SkipInternal
     public static function addInternalClass($classes, $level = 0)
     {
         if (\is_int($level) === false) {
-            throw new InvalidArgumentException(\sprintf('level must be an integer'));
+            throw new InvalidArgumentException(\sprintf(
+                'level must be an integer. %s provided.',
+                \gettype($level)
+            ));
         }
         if (\is_array($classes) === false) {
             $classes = array($classes => $level);

src/Backtrace/Xdebug.php

@@ -4,7 +4,7 @@
  * @package   Backtrace
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2020-2023 Brad Kent
+ * @copyright 2020-2024 Brad Kent
  * @version   v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
@@ -26,7 +26,7 @@ class Xdebug
      *
      * @param int $maxDepth set xdebug.var_display_max_depth ini/config
      *
-     * @return array|false
+     * @return array[]|false
      *
      * @see https://bugs.xdebug.org/view.php?id=695
      * @see https://bugs.xdebug.org/view.php?id=1529
@@ -39,7 +39,7 @@ public static function getFunctionStack($maxDepth = 3)
         }
         $vdmdKey = 'xdebug.var_display_max_depth';
         $vdmdBak = \ini_get($vdmdKey);
-        \ini_set($vdmdKey, $maxDepth);
+        \ini_set($vdmdKey, (string) $maxDepth);
         $stack = \xdebug_get_function_stack();
         \ini_set($vdmdKey, $vdmdBak);
         // phpcs:ignore SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions.NonFullyQualified

src/Container/Container.php

@@ -6,7 +6,7 @@
  * @package   PHPDebugConsole
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2014-2022 Brad Kent
+ * @copyright 2014-2024 Brad Kent
  * @version   v3.0
  */
 
@@ -31,6 +31,7 @@
  */
 class Container implements \ArrayAccess
 {
+    /** @var array */
     private $cfg = array(
         'allowOverride' => false,  // whether can update alreay built service
         'onInvoke' => null, // callable
@@ -43,8 +44,10 @@ class Container implements \ArrayAccess
      */
     private $factories;
 
+    /** @var array<string, bool> */
     private $invoked = array();  // keep track of invoked service closures
 
+    /** @var array<string, bool> */
     private $keys = array();
 
     /**
@@ -55,8 +58,10 @@ class Container implements \ArrayAccess
      */
     private $protected;
 
+    /** @var array<string, mixed> */
     private $raw = array();
 
+    /** @var array<string, mixed> */
     private $values = array();
 
     /**
@@ -207,26 +212,26 @@ public function offsetGet($name)
      * ArrayAccess
      * Sets a parameter or an object.
      *
-     * @param string $name  The unique identifier for the parameter or object
-     * @param mixed  $value The value of the parameter or a closure to define an object
+     * @param string $offset The unique identifier for the parameter or object
+     * @param mixed  $value  The value of the parameter or a closure to define an object
      *
      * @throws \RuntimeException Prevent override of a already built service
      * @return void
      */
     #[\ReturnTypeWillChange]
-    public function offsetSet($name, $value)
+    public function offsetSet($offset, $value)
     {
-        if (isset($this->invoked[$name]) && $this->cfg['allowOverride'] === false) {
+        if (isset($this->invoked[$offset]) && $this->cfg['allowOverride'] === false) {
             throw new \RuntimeException(
-                \sprintf('Cannot update "%s" after it has been instantiated.', $name)
+                \sprintf('Cannot update "%s" after it has been instantiated.', $offset)
             );
         }
 
-        $this->keys[$name] = true;
-        $this->values[$name] = $value;
+        $this->keys[$offset] = true;
+        $this->values[$offset] = $value;
         unset(
-            $this->invoked[$name],
-            $this->raw[$name]
+            $this->invoked[$offset],
+            $this->raw[$offset]
         );
     }
 

src/CurlHttpMessage/Client.php

@@ -2,11 +2,14 @@
 
 namespace bdk\CurlHttpMessage;
 
+use bdk\CurlHttpMessage\Exception\NetworkException;
 use bdk\CurlHttpMessage\Factory;
 use bdk\CurlHttpMessage\HandlerStack;
 use bdk\Promise\PromiseInterface;
 use InvalidArgumentException;
 use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\UriInterface;
 
 /**
  * Lightweight PSR-7 (HttpMessage) based cURL client

src/CurlHttpMessage/ClientAsync.php

@@ -4,6 +4,7 @@
 
 use bdk\Promise;
 use bdk\Promise\EachPromise;
+use bdk\Promise\PromiseInterface;
 use InvalidArgumentException;
 use Psr\Http\Message\RequestInterface;
 

src/CurlHttpMessage/CurlReqRes.php

@@ -15,7 +15,7 @@
  */
 class CurlReqRes
 {
-    /** @var resource|CurlHandle */
+    /** @var resource|\CurlHandle */
     private $curlHandle;
 
     /** @var bool */
@@ -127,7 +127,7 @@ public function finish()
      *
      * @param bool $create (false) whether handle should be created
      *
-     * @return resource|CurlHandle|null
+     * @return resource|\CurlHandle|null
      */
     public function getCurlHandle($create = false)
     {
@@ -143,7 +143,7 @@ public function getCurlHandle($create = false)
      *
      * If setting, also sets curl options
      *
-     * @param resource|CurlHandle|null $curlHandle curlHandle
+     * @param resource|\CurlHandle|null $curlHandle curlHandle
      *
      * @return self
      */

src/Debug/AbstractComponent.php

@@ -6,7 +6,7 @@
  * @package   PHPDebugConsole
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2014-2022 Brad Kent
+ * @copyright 2014-2024 Brad Kent
  * @version   v3.0
  */
 
@@ -20,5 +20,6 @@
  */
 abstract class AbstractComponent extends BaseAbstractComponent implements ConfigurableInterface
 {
+    /** @var callable */
     protected $setCfgMergeCallable = 'array_merge';
 }

src/Debug/AbstractDebug.php

@@ -23,23 +23,32 @@
 
 /**
  * Handle underlying Debug bootstraping and config
+ *
+ * @psalm-consistent-constructor
  */
 class AbstractDebug
 {
     /** @var \bdk\Debug\Config */
     protected $config;
 
-    /** @var \bdk\Container */
+    /** @var Container */
     protected $container;
+    /** @var Container */
     protected $serviceContainer;
 
-    /** @var \bdk\Debug */
+    /** @var Debug|null */
     protected static $instance;
 
+    /** @var array<string, array> */
     protected static $methodDefaultArgs = array();
+
+    /** @var Debug|null */
     protected $parentInstance;
+
+    /** @var Debug */
     protected $rootInstance;
 
+    /** @var array<int, string> */
     protected $readOnly = array(
         'parentInstance',
         'rootInstance',
@@ -50,7 +59,7 @@ class AbstractDebug
      *
      * @param array $cfg config
      */
-    public function __construct($cfg)
+    public function __construct($cfg = array())
     {
         if (!isset(self::$instance)) {
             // self::getInstance() will always return initial/first instance

src/Debug/Collector/MySqli.php

@@ -6,7 +6,7 @@
  * @package   PHPDebugConsole
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2014-2022 Brad Kent
+ * @copyright 2014-2024 Brad Kent
  * @version   v3.0
  */
 
@@ -173,9 +173,9 @@ public function prepare($query)
      * {@inheritDoc}
      */
     #[\ReturnTypeWillChange]
-    public function query($query, $resultmode = MYSQLI_STORE_RESULT)
+    public function query($query, $resultMode = MYSQLI_STORE_RESULT)
     {
-        return $this->profileCall('query', $query, array($query, $resultmode));
+        return $this->profileCall('query', $query, array($query, $resultMode));
     }
 
     /**

src/Debug/LogEntry.php

@@ -6,7 +6,7 @@
  * @package   PHPDebugConsole
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
- * @copyright 2014-2022 Brad Kent
+ * @copyright 2014-2024 Brad Kent
  * @version   v3.0
  */
 
@@ -24,7 +24,7 @@ class LogEntry extends Event implements JsonSerializable
     /**
      * Regular expression for determining if argument contains "substitutions"
      *
-     * @var string
+     * @var non-empty-string
      */
     public $subRegex = '/%
         (?: