adding callback support

Author: dcarbone

README.md

@@ -55,6 +55,129 @@ class stdClass#56 (1) {
 */
 ```
 
+## Callback
+If you wish to sometimes manually handle the merging of two values, you may do so using the provided `_callback`
+functions.
+
+### Callback providing
+
+You may provide any php-callable notation you wish, including:
+
+```php
+object_merge_callback(0, 'function_name', ...$objects);
+object_merge_callback(0, $closure, ...$objects);
+object_merge_callback(0, ['FQCN', 'function_name'], ...$objects);
+object_merge_callback(0, [$instance, 'function_name'], ...$objects);
+```
+
+### Callback arguments
+
+The callback function will be provided exactly one parameter, and it will always be an instance of 
+[ObjectMergeState](./src/ObjectMergeState.php).
+
+### Callback response
+
+If the callback function returns _anything_ other than an instance of [ObjectMergeResult](./src/ObjectMergeResult.php),
+it is used outright as the value of the merge, without further processing or recursion.
+
+See comments on [ObjectMergeResult](./src/ObjectMergeResult.php) for how each parameter is handled. 
+
+```php
+use DCarbone\ObjectMergeResult;
+use DCarbone\ObjectMergeState;
+
+/**
+ * @param ObjectMergeState $state
+ * @return ObjectMergeResult|null
+ */
+function merge_int_to_null(ObjectMergeState $state)
+{
+    if (is_int($state->leftValue)) {
+        return null;
+    }
+    return new ObjectMergeResult(true);
+}
+
+/**
+ * @return ObjectMergeResult
+ */
+function merge_always_continue()
+{
+    return new ObjectMergeResult(true);
+}
+
+/**
+ * @param ObjectMergeState $state
+ * @return mixed
+ */
+function merge_use_left_side(ObjectMergeState $state)
+{
+    return $state->leftValue;
+}
+
+$o1 = json_decode('{"int1":1,"str1":"string","int2":2,"float":3.2,"arr":[]}');
+$o2 = json_decode('{"int1":-3432,"str1":"sandwiches","int2":' . PHP_INT_MAX . ',"float":2.3,"arr":["onevalue"]}');
+
+$out1 = object_merge_callback(0, 'merge_int_to_null', $o1, $o2);
+$out2 = object_merge_callback(0, 'merge_always_continue', $o1, $o2);
+$out3 = object_merge_callback(0, 'merge_use_left_side', $o1, $o2);
+
+var_dump($out1);
+/*
+class stdClass#87 (5) {
+  public $int1 =>
+  NULL
+  public $str1 =>
+  string(10) "sandwiches"
+  public $int2 =>
+  NULL
+  public $float =>
+  double(2.3)
+  public $arr =>
+  array(1) {
+    [0] =>
+    string(8) "onevalue"
+  }
+}
+*/
+
+var_dump($out2);
+/*
+class stdClass#160 (5) {
+  public $int1 =>
+  int(-3432)
+  public $str1 =>
+  string(10) "sandwiches"
+  public $int2 =>
+  int(9223372036854775807)
+  public $float =>
+  double(2.3)
+  public $arr =>
+  array(1) {
+    [0] =>
+    string(8) "onevalue"
+  }
+}
+*/
+
+var_dump($out3);
+/*
+class stdClass#123 (5) {
+  public $int1 =>
+  int(1)
+  public $str1 =>
+  string(6) "string"
+  public $int2 =>
+  int(2)
+  public $float =>
+  double(3.2)
+  public $arr =>
+  array(0) {
+  }
+}
+*/
+``` 
+
 ## Merge Options
 The `object_merge` and `object_merge_recursive` functions have sister functions named `object_merge_opts` and
 `object_merge_recursive_opts` respectively.  Each of these has a required `$opts` argument that must be a bitwise

composer.json

@@ -34,7 +34,8 @@
   "autoload-dev": {
     "files": [
       "files/constants.php",
-      "files/functions.php"
+      "files/functions.php",
+      "tests/functions.php"
     ],
     "psr-4": {
       "DCarbone\\": "src/",

files/functions.php

@@ -74,4 +74,28 @@ function object_merge_recursive_opts($opts, stdClass ...$objects)
     {
         return ObjectMerge::mergeRecursiveOpts($opts, ...$objects);
     }
+}
+if (!function_exists('object_merge_callback')) {
+    /**
+     * @param int $opts
+     * @param callable $cb
+     * @param stdClass ...$objects
+     * @return stdClass|null
+     */
+    function object_merge_callback($opts, $cb, stdClass ...$objects)
+    {
+        return ObjectMerge::mergeCallback($opts, $cb, ...$objects);
+    }
+}
+if (!function_exists('object_merge_recursive_callback')) {
+    /**
+     * @param int $opts
+     * @param callable $cb
+     * @param stdClass ...$objects
+     * @return stdClass|null
+     */
+    function object_merge_recursive_callback($opts, $cb, stdClass ...$objects)
+    {
+        return ObjectMerge::mergeRecursiveCallback($opts, $cb, ...$objects);
+    }
 }

src/ObjectMerge.php

@@ -43,32 +43,34 @@ class ObjectMerge
     const OBJECT_T = 'object';
 
     /** @var bool */
-    private static $_recurse;
+    private static $_recursive;
     /** @var int */
     private static $_opts;
+    /** @var callable */
+    private static $_cb;
 
     /** @var int */
     private static $_depth = -1;
     /** @var array */
     private static $_context = [];
 
     // list of types considered "simple"
-    private static $_SIMPLE_TYPES = array(
+    private static $_SIMPLE_TYPES = [
         self::NULL_T,
         self::RESOURCE_T,
         self::STRING_T,
         self::BOOLEAN_T,
         self::INTEGER_T,
         self::DOUBLE_T
-    );
+    ];
 
     /**
      * @param stdClass ...$objects
      * @return stdClass|null
      */
     public function __invoke(stdClass ...$objects)
     {
-        return self::_doMerge(false, self::DEFAULT_OPTS, $objects);
+        return self::_doMerge(false, self::DEFAULT_OPTS, null, $objects);
     }
 
     /**
@@ -77,7 +79,7 @@ public function __invoke(stdClass ...$objects)
      */
     public static function merge(stdClass ...$objects)
     {
-        return self::_doMerge(false, self::DEFAULT_OPTS, $objects);
+        return self::_doMerge(false, self::DEFAULT_OPTS, null, $objects);
     }
 
     /**
@@ -86,7 +88,7 @@ public static function merge(stdClass ...$objects)
      */
     public static function mergeRecursive(stdClass ...$objects)
     {
-        return self::_doMerge(true, self::DEFAULT_OPTS, $objects);
+        return self::_doMerge(true, self::DEFAULT_OPTS, null, $objects);
     }
 
     /**
@@ -96,7 +98,7 @@ public static function mergeRecursive(stdClass ...$objects)
      */
     public static function mergeOpts($opts, stdClass ...$objects)
     {
-        return self::_doMerge(false, $opts, $objects);
+        return self::_doMerge(false, $opts, null, $objects);
     }
 
     /**
@@ -106,7 +108,69 @@ public static function mergeOpts($opts, stdClass ...$objects)
      */
     public static function mergeRecursiveOpts($opts, stdClass ...$objects)
     {
-        return self::_doMerge(true, $opts, $objects);
+        return self::_doMerge(true, $opts, null, $objects);
+    }
+
+    /**
+     * @param int $opts
+     * @param callable $cb
+     * @param stdClass ...$objects
+     * @return stdClass
+     */
+    public static function mergeCallback($opts, $cb, stdClass ...$objects)
+    {
+        return self::_doMerge(false, $opts, $cb, $objects);
+    }
+
+    /**
+     * @param int $opts
+     * @param callable $cb
+     * @param stdClass ...$objects
+     * @return stdClass
+     */
+    public static function mergeRecursiveCallback($opts, $cb, stdClass ...$objects)
+    {
+        return self::_doMerge(true, $opts, $cb, $objects);
+    }
+
+    /**
+     * @return ObjectMergeState
+     */
+    public static function partialState()
+    {
+        return self::_partialState();
+    }
+
+    /**
+     * @return ObjectMergeState
+     */
+    private static function _partialState()
+    {
+        $state = new ObjectMergeState();
+
+        $state->recursive = self::$_recursive;
+        $state->opts = self::$_opts;
+        $state->depth = self::$_depth;
+        $state->context = self::$_context;
+
+        return $state;
+    }
+
+    /**
+     * @param string|int $key
+     * @param mixed $leftValue
+     * @param mixed $rightValue
+     * @return ObjectMergeState
+     */
+    private static function _fullState($key, $leftValue, $rightValue)
+    {
+        $state = self::_partialState();
+
+        $state->key = $key;
+        $state->leftValue = $leftValue;
+        $state->rightValue = $rightValue;
+
+        return $state;
     }
 
     private static function _down()
@@ -127,9 +191,9 @@ private static function _up()
     private static function _exceptionMessage($prefix)
     {
         return sprintf(
-            '%s - $recurse=%s; $opts=%d; $depth=%d; $context=%s',
+            '%s - $recursive=%s; $opts=%d; $depth=%d; $context=%s',
             $prefix,
-            self::$_recurse,
+            self::$_recursive,
             self::$_opts,
             self::$_depth,
             implode('->', self::$_context)
@@ -270,6 +334,23 @@ private static function _mergeValues($key, $leftValue, $rightValue)
     {
         self::$_context[self::$_depth] = $key;
 
+        if (isset(self::$_cb)) {
+            $res = call_user_func(self::$_cb, self::_fullState($key, $leftValue, $rightValue));
+            $resT = gettype($res);
+            if (self::OBJECT_T === $resT) {
+                if ($res instanceof ObjectMergeResult && !$res->shouldContinue()) {
+                    $finalValue = $res->getFinalValue();
+                    if (OBJECT_MERGE_UNDEFINED !== $finalValue) {
+                        return $finalValue;
+                    }
+                    $leftValue = $res->getLeftValue();
+                    $rightValue = $res->getRightValue();
+                }
+            } else {
+                return $res;
+            }
+        }
+
         $leftUndefined = object_merge_value_undefined($leftValue, self::$_opts);
         $rightUndefined = object_merge_value_undefined($rightValue, self::$_opts);
 
@@ -310,7 +391,7 @@ private static function _mergeValues($key, $leftValue, $rightValue)
             return self::_mergeValues($key, self::_newEmptyValue($rightValue), $rightValue);
         }
 
-        if (!self::$_recurse || in_array($leftType, self::$_SIMPLE_TYPES, true)) {
+        if (!self::$_recursive || in_array($leftType, self::$_SIMPLE_TYPES, true)) {
             return $rightValue;
         }
 
@@ -322,12 +403,13 @@ private static function _mergeValues($key, $leftValue, $rightValue)
     }
 
     /**
-     * @param bool $recurse
+     * @param bool $recursive
      * @param int $opts
+     * @param callable|null $cb
      * @param array $objects
      * @return mixed|null
      */
-    private static function _doMerge($recurse, $opts, array $objects)
+    private static function _doMerge($recursive, $opts, $cb, array $objects)
     {
         if ([] === $objects) {
             return null;
@@ -336,8 +418,9 @@ private static function _doMerge($recurse, $opts, array $objects)
         $root = null;
 
         // set state
-        self::$_recurse = $recurse;
+        self::$_recursive = $recursive;
         self::$_opts = $opts;
+        self::$_cb = $cb;
 
         foreach ($objects as $object) {
             if (null === $object) {
@@ -349,14 +432,15 @@ private static function _doMerge($recurse, $opts, array $objects)
                 continue;
             }
 
-            $root = self::_mergeObjectValues($root, !$recurse ? clone $object : $object);
+            $root = self::_mergeObjectValues($root, !$recursive ? clone $object : $object);
         }
 
         // reset state
         self::$_depth = -1;
         self::$_context = [];
-        self::$_recurse = false;
+        self::$_recursive = false;
         self::$_opts = 0;
+        self::$_cb = null;
 
         return $root;
     }