php 8.4 support (implicit nullable types deprecation notice)

properties:  collect 'isDeprecated'
require bdk/http-message: "^1.3 || ^2.3 || ^3.3"
ServiceProvider:  serverRequest now instance of bdk\HttpMessage\ServerRequestExtended
ServiceProvider - organize service definitions
Container: add extend() method
Fix misc Issues with abstracting an interface
phpDoc @deprecated, @SInCE, & @Version tags now parsed into version & desc values

composer.json

@@ -55,7 +55,7 @@
   },
   "require": {
     "php": ">=5.4.0",
-    "bdk/http-message": "^1.2 || ^2.0 || ^3.0"
+    "bdk/http-message": "^1.3 || ^2.3 || ^3.3"
   },
   "require-dev": {
     "bdk/devutil": "dev-master",

phpunit.xml.dist

@@ -33,6 +33,7 @@
     </report>
     -->
     <exclude>
+      <file>src/Debug/Collector/DoctrineLogger/CompatTrait_legacy.php</file>
       <file>src/Debug/Dump/charData.php</file>
       <directory>src/Debug/Framework</directory>
       <directory>src/Debug/node_modules</directory>

src/Backtrace/Backtrace.php

@@ -5,7 +5,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2020-2024 Brad Kent
- * @version   v2.2
+ * @since     v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
 

src/Backtrace/Context.php

@@ -5,7 +5,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2020-2024 Brad Kent
- * @version   v2.2
+ * @since     v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
 

src/Backtrace/Normalizer.php

@@ -5,7 +5,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2020-2024 Brad Kent
- * @version   v2.2
+ * @since     v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
 
@@ -128,7 +128,7 @@ private static function normalizeFrameFunction(array $frame)
             // xdebug_get_function_stack
             $frame['function'] = $matches[1];
         }
-        if (\preg_match('/^(.*)\{closure(?::(.*):(\d*)-(\d*))?\}$/', (string) $frame['function'])) {
+        if (\preg_match('/^([^\{]*)\{closure(?::(.*):(\d*)(?:-(\d*))?)?\}$/', (string) $frame['function'])) {
             // both debug_backtrace and xdebug_get_function_stack may have the namespace prefix
             //   xdebug provides the filepath, start and end lines
             $frame['function'] = '{closure}';

src/Backtrace/SkipInternal.php

@@ -5,7 +5,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2020-2024 Brad Kent
- * @version   v2.2
+ * @since     v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
 

src/Backtrace/Xdebug.php

@@ -5,7 +5,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2020-2024 Brad Kent
- * @version   v2.2
+ * @since     v2.2
  * @link      http://www.github.com/bkdotcom/Backtrace
  */
 

src/Container/Container.php

@@ -7,13 +7,17 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2014-2024 Brad Kent
- * @version   v3.0
+ * @since     v3.0
  */
 
 namespace bdk;
 
+use ArrayAccess;
 use bdk\Container\ServiceProviderInterface;
+use InvalidArgumentException;
 use OutOfBoundsException;
+use RuntimeException;
+use SplObjectStorage;
 
 /**
  * Container
@@ -30,36 +34,51 @@
  * @author Fabien Potencier
  * @author Brad Kent <[email protected]>
  */
-class Container implements \ArrayAccess
+class Container implements ArrayAccess
 {
     /** @var array */
     private $cfg = array(
         'allowOverride' => false,  // whether can update already built service
         'onInvoke' => null, // callable
     );
 
+    /**
+     * Closures used to modify / extend service definitions when invoked
+     *
+     * @var array<string,Closure>
+     */
+    private $extenders;
+
     /**
      * Closures flagged as factories
      *
-     * @var \SplObjectStorage
+     * @var SplObjectStorage
      */
     private $factories;
 
-    /** @var array<string,bool> */
-    private $invoked = array();  // keep track of invoked service closures
+    /**
+     * Keep track of invoked service closures
+     *
+     * @var array<string,bool>
+     */
+    private $invoked = array();
 
     /** @var array<string,bool> */
     private $keys = array();
 
     /**
-     * wrap anonymous functions with the protect() method to store them as value
+     * Wrap anonymous functions with the protect() method to store them as value
      *  vs treating as service
      *
-     * @var \SplObjectStorage
+     * @var SplObjectStorage
      */
     private $protected;
 
-    /** @var array<string,mixed> */
+    /**
+     * Populated with the original raw service/factory closure when invoked
+     *
+     * @var array<string,mixed>
+     */
     private $raw = array();
 
     /** @var array<string,mixed> */
@@ -75,13 +94,38 @@ class Container implements \ArrayAccess
      */
     public function __construct($values = array(), $cfg = array())
     {
-        $this->factories = new \SplObjectStorage();
-        $this->protected = new \SplObjectStorage();
+        $this->factories = new SplObjectStorage();
+        $this->protected = new SplObjectStorage();
 
         $this->setCfg($cfg);
         $this->setValues($values);
     }
 
+    /**
+     * Extends an object definition.
+     *
+     * Useful for
+     *  - Extend an existing object definition without necessarily loading that object.
+     *  - Ensure user-supplied factory is decorated with additional functionality.
+     *
+     * The callable should:
+     *  - 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 callable $callable A service definition to extend the original
+     *
+     * @return void
+     */
+    public function extend($name, $callable)
+    {
+        $this->assertExists($name);
+        $this->assertInvokable($this->values[$name]);
+        $this->assertInvokable($callable);
+
+        $this->extenders[$name] = $callable;
+    }
+
     /**
      * Marks a callable as being a factory service.
      * A new instance will be returned each time it is accessed
@@ -93,19 +137,17 @@ public function __construct($values = array(), $cfg = array())
      * @param callable $invokable A service definition to be used as a factory
      *
      * @return callable The passed callable
-     * @throws \InvalidArgumentException Service definition has to be a closure or an invokable object
+     * @throws InvalidArgumentException Service definition has to be a closure or an invokable object
      */
     public function factory($invokable)
     {
-        if (\is_object($invokable) === false || \method_exists($invokable, '__invoke') === false) {
-            throw new \InvalidArgumentException('Closure or invokable object expected.');
-        }
+        $this->assertInvokable($invokable);
         $this->factories->attach($invokable);
         return $invokable;
     }
 
     /**
-     * Finds an entry of the container by its identifier and returns it.
+     * Finds an entry by its identifier and returns it.
      *
      * @param string $name Identifier of the entry to look for.
      *
@@ -158,8 +200,7 @@ public function needsInvoked($name)
     }
 
     /**
-     * ArrayAccess
-     * Checks if a parameter or an object is set.
+     * ArrayAccess: Checks if a parameter or an object is set.
      *
      * @param string $name The unique identifier for the parameter or object
      *
@@ -172,8 +213,7 @@ public function offsetExists($name)
     }
 
     /**
-     * ArrayAccess
-     * Gets a parameter or an object.
+     * ArrayAccess: Gets a parameter or an object.
      *
      * @param string $name The unique identifier for the parameter or object
      *
@@ -184,46 +224,43 @@ public function offsetExists($name)
     public function offsetGet($name)
     {
         $this->assertExists($name);
+
         if ($this->needsInvoked($name) === false) {
             return $this->values[$name];
         }
+
         if (isset($this->factories[$this->values[$name]])) {
             // we're a factory
             $val = $this->values[$name]($this);
-            if (\is_callable($this->cfg['onInvoke'])) {
-                $this->cfg['onInvoke']($val, $name, $this);
-            }
-            return $val;
+            return $this->onInvoke($name, $val);
         }
+
         // we're a service
         $raw = $this->values[$name];
         $this->invoked[$name] = true;
         $this->raw[$name] = $raw;
 
         $val = $raw($this);
-        if (\is_callable($this->cfg['onInvoke'])) {
-            $this->cfg['onInvoke']($val, $name, $this);
-        }
+        $val = $this->onInvoke($name, $val);
         $this->values[$name] = $val;
 
         return $val;
     }
 
     /**
-     * ArrayAccess
-     * Sets a parameter or an object.
+     * ArrayAccess: Sets a parameter or 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
+     * @throws RuntimeException Prevent override of a already built service
      * @return void
      */
     #[\ReturnTypeWillChange]
     public function offsetSet($offset, $value)
     {
         if (isset($this->invoked[$offset]) && $this->cfg['allowOverride'] === false) {
-            throw new \RuntimeException(
+            throw new RuntimeException(
                 \sprintf('Cannot update "%s" after it has been instantiated.', $offset)
             );
         }
@@ -237,8 +274,7 @@ public function offsetSet($offset, $value)
     }
 
     /**
-     * ArrayAccess
-     * Unsets a parameter or an object.
+     * ArrayAccess: Unsets a parameter or an object.
      *
      * @param string $name The unique identifier for the parameter or object
      *
@@ -276,13 +312,11 @@ public function offsetUnset($name)
      * @param callable $invokable A callable to protect from being evaluated
      *
      * @return callable The passed callable
-     * @throws \InvalidArgumentException Service definition has to be a closure or an invokable object
+     * @throws InvalidArgumentException Service definition has to be a closure or an invokable object
      */
     public function protect($invokable)
     {
-        if (\is_object($invokable) === false || \method_exists($invokable, '__invoke') === false) {
-            throw new \InvalidArgumentException('Closure or invokable object expected.');
-        }
+        $this->assertInvokable($invokable);
         $this->protected->attach($invokable);
         return $invokable;
     }
@@ -375,4 +409,57 @@ private function assertExists($name)
             );
         }
     }
+
+    /**
+     * Assert that the identifier exists
+     *
+     * @param string $name Identifier of entry to check
+     *
+     * @return void
+     *
+     * @throws InvalidArgumentException If the identifier is not defined
+     */
+    private function assertInvokable($val)
+    {
+        if (\is_object($val) === false || \method_exists($val, '__invoke') === false) {
+            throw new InvalidArgumentException(\sprintf(
+                'Closure or invokable object expected.  %s provided',
+                $this->getDebugType($val)
+            ));
+        }
+    }
+
+    /**
+     * Gets the type name of a variable in a way that is suitable for debugging
+     *
+     * @param mixed $value Value to inspect
+     *
+     * @return string
+     */
+    protected static function getDebugType($value)
+    {
+        return \is_object($value)
+            ? \get_class($value)
+            : \gettype($value);
+    }
+
+    /**
+     * Undocumented function
+     *
+     * @param string $name  The service or factory name
+     * @param mixed  $value The value returned by the definition
+     *
+     * @return mixed the value (possibly modified by extenders)
+     */
+    private function onInvoke($name, $value)
+    {
+        if (isset($this->extenders[$name])) {
+            $callable = $this->extenders[$name];
+            $value = $callable($value, $this);
+        }
+        if (\is_callable($this->cfg['onInvoke'])) {
+            $this->cfg['onInvoke']($value, $name, $this);
+        }
+        return $value;
+    }
 }

src/Container/ServiceProviderInterface.php

@@ -7,7 +7,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2014-2024 Brad Kent
- * @version   v3.0
+ * @since     v3.0
  */
 
 namespace bdk\Container;

src/Container/Utility.php

@@ -7,7 +7,7 @@
  * @author    Brad Kent <[email protected]>
  * @license   http://opensource.org/licenses/MIT MIT
  * @copyright 2014-2024 Brad Kent
- * @version   v3.1
+ * @since     v3.1
  */
 
 namespace bdk\Container;

src/CurlHttpMessage/AbstractClient.php

@@ -266,7 +266,7 @@ public function request($method, $uri, array $options = array())
     /**
      * apply options to request
      *
-     * @param RequestInterface     $request Request instance
+     * @param RequestInterface    $request Request instance
      * @param array<string,mixed> $options options
      *
      * @return RequestInterface