adding another test case and updating documentation a bit

Author: dcarbone

README.md

@@ -207,4 +207,30 @@ class stdClass#56 (1) {
   }
 }
 */
+```
+
+#### `OBJECT_MERGE_OPT_NULL_AS_UNDEFINED`
+
+When specified, NULL values are treated as UNDEFINED, meaning they will not cause a type conflict to be risen and the
+non-null value will be used in the merge.
+
+This can be useful if you do not want to have _all_ type conflicts to be overwritten with the right-hand value, but want
+to ignore null to not null differences.
+
+Example:
+```php
+$o1 = json_decode('{"key":"value"}');
+$o2 = json_decode('{"key":null}');
+$o3 = json_decode('{"key":"different value"}');
+
+$out = object_merge_recursive_opts(OBJECT_MERGE_OPT_NULL_AS_UNDEFINED, $o1, $o2, $o3); 
+
+var_dump($out);
+
+/*
+class stdClass#161 (1) {
+  public $key =>
+  string(15) "different value"
+}
+*/
 ```

tests/ObjectMergeTest.php

@@ -163,6 +163,16 @@ class ObjectMergeTest extends TestCase
             'recurse'  => true,
             'opts'     => OBJECT_MERGE_OPT_MERGE_ARRAY_VALUES | OBJECT_MERGE_OPT_UNIQUE_ARRAYS
         ],
+        [
+            'objects'  => [
+                '{"key":"value"}',
+                '{"key":null}',
+                '{"key":"different value"}'
+            ],
+            'expected' => '{"key":"different value"}',
+            'recurse'  => false,
+            'opts'     => OBJECT_MERGE_OPT_NULL_AS_UNDEFINED
+        ],
         [
             'objects'  => [
                 '{"title":"Unique Clients Trend Over Time","queryName":"trendTable","systemOwnerOnly":false,"component":"ReportTable","defaultParameters":{"granularity":"fifteen_minute","metric":"traffic","limit":10},"layout":{"width":"full","widgetTheme":"blue","headers":[{"component":"GranularityFilter","name":"limit","options":{"traffic":"User Traffic","rxBytes":"Rx User","txBytes":"Tx User","0":"All","10":"Top 10 Clients","20":"Top 20 Clients","50":"Top 50 Clients","100":"Top 100 Clients"}},{"component":"PeriodFilter","query":"topClientTrafficPercentage","content":{"text":"These ${name} consume <b>${percentage}</b> ( <b>${traffic}</b> ) of all user traffic ( <b>${totalTraffic}</b> ).","formats":{"totalTraffic":"bytesFormat","percentage":"percentFormat","traffic":"bytesFormat"}}}],"format":"bytesFormat","colors":["#5BA1E0","#76CEF5","#D9E6F5"],"drillDownRoute":"/report/client/${x}","subSections":[{"component":"LineChart","layout":{"width":"full","label":"authMethod","value":"clientCount","title":{"default":"Clients"},"formatMetadata":{"totalClients":"countFormat","subTitle":"${templateData.totalClients}"},"labelFormat":"label-value2","series":[{"color":"#66b1e8","key":"All Radios","values":"unique_users"},{"color":"#46a3bb","key":"2.4 GHz","values":"unique_users_2-4","area":true},{"color":"#beeee0","key":"5 GHz","values":"unique_users_5","area":true},{"color":"#F17CB0"},{"color":"#8c7024"},{"color":"#B276B2"},{"color":"#eddc44"},{"color":"#F15854"},{"color":"#26657c"},{"color":"#4D4D4D"}],"xAxisType":"time","yAxisType":"countFormat"},"title":"Client Count"},{"component":"LineChart","layout":{"hideLegendLabels":true,"xAxisType":"time","yAxisType":"bytesFormat","width":"full","series":[{"color":"#66b1e8","disabled":false,"key":"User Traffic","values":"traffic"},{"color":"#4e9ee6","disabled":false,"key":"Rx User","values":"rxBytes","area":true},{"color":"#cee9fa","disabled":true,"key":"Tx User","values":"txBytes","area":true},{"color":"#F17CB0","disabled":true},{"color":"#8c7024","disabled":true},{"color":"#B276B2","disabled":true},{"color":"#eddc44","disabled":true},{"color":"#F15854","disabled":true},{"color":"#26657c","disabled":true},{"color":"#4D4D4D","disabled":true}]},"title":"Traffic"}],"columns":[{"columnName":"timestamp","displayName":"Time Period","customComponent":"Interval"},{"columnName":"unique_users_2-4","displayName":"2.4 GHz","customComponent":"PercentBar","drillDownRoute":"/report/client/${clientMac}","color":"#5BE0C7"},{"columnName":"unique_users_5","displayName":"5 GHz","customComponent":"PercentBar","drillDownRoute":"/report/client/${clientMac}","hidden":true,"color":"#5BE0C7"},{"columnName":"unique_users","displayName":"Total","customComponent":"PercentBar","color":"#5BE0C7"},{"columnName":"rxBytes","displayName":"Rx User","customComponent":"PercentBar","format":"bytesFormat"},{"columnName":"txBytes","displayName":"Tx User","customComponent":"PercentBar","format":"bytesFormat"},{"columnName":"traffic","displayName":"User Traffic","customComponent":"PercentBar","format":"bytesFormat"},{"columnName":"manufacturer","displayName":"Manufacturer","hidden":true},{"columnName":"osType","displayName":"OS","hidden":true}]},"url":null,"id":16}',
@@ -171,7 +181,7 @@ class ObjectMergeTest extends TestCase
             'expected' => '{"title":"Top Clients by Traffic Percentile","queryName":"topPercentile","systemOwnerOnly":false,"component":"ReportTable","defaultParameters":{"granularity":"all","metric":"traffic","limit":10},"layout":{"width":"full","widgetTheme":"blue","headers":[{"component":"GranularityFilter","name":"limit","options":{"traffic":"User Traffic","rxBytes":"Rx User","txBytes":"Tx User","0":"All","10":"Top 10 Clients","20":"Top 20 Clients","50":"Top 50 Clients","100":"Top 100 Clients"}},{"component":"PeriodFilter","query":"topClientTrafficPercentage","content":{"text":"These ${name} consume <b>${percentage}</b> ( <b>${traffic}</b> ) of all user traffic ( <b>${totalTraffic}</b> ).","formats":{"totalTraffic":"bytesFormat","percentage":"percentFormat","traffic":"bytesFormat"}}}],"format":"bytesFormat","colors":["#5BA1E0","#76CEF5","#D9E6F5"],"drillDownRoute":"/report/client/${x}","subSections":[{"component":"LineChart","layout":{"width":"full","label":"authMethod","value":"clientCount","title":{"default":"Clients"},"formatMetadata":{"totalClients":"countFormat","subTitle":"${templateData.totalClients}"},"labelFormat":"label-value2","series":[{"color":"#66b1e8","key":"All Radios","values":"unique_users"},{"color":"#46a3bb","key":"2.4 GHz","values":"unique_users_2-4","area":true},{"color":"#beeee0","key":"5 GHz","values":"unique_users_5","area":true},{"color":"#F17CB0"},{"color":"#8c7024"},{"color":"#B276B2"},{"color":"#eddc44"},{"color":"#F15854"},{"color":"#26657c"},{"color":"#4D4D4D"}],"xAxisType":"time","yAxisType":"countFormat"},"title":"Client Count"},{"component":"LineChart","layout":{"hideLegendLabels":true,"xAxisType":"time","yAxisType":"bytesFormat","width":"full","series":[{"color":"#66b1e8","disabled":false,"key":"User Traffic","values":"traffic"},{"color":"#4e9ee6","disabled":false,"key":"Rx User","values":"rxBytes","area":true},{"color":"#cee9fa","disabled":true,"key":"Tx User","values":"txBytes","area":true},{"color":"#F17CB0","disabled":true},{"color":"#8c7024","disabled":true},{"color":"#B276B2","disabled":true},{"color":"#eddc44","disabled":true},{"color":"#F15854","disabled":true},{"color":"#26657c","disabled":true},{"color":"#4D4D4D","disabled":true}]},"title":"Traffic"}],"columns":[{"columnName":"timestamp","displayName":"Time Period","customComponent":"Interval"},{"columnName":"unique_users_2-4","displayName":"2.4 GHz","customComponent":"PercentBar","drillDownRoute":"/report/client/${clientMac}","color":"#5BE0C7"},{"columnName":"unique_users_5","displayName":"5 GHz","customComponent":"PercentBar","drillDownRoute":"/report/client/${clientMac}","hidden":true,"color":"#5BE0C7"},{"columnName":"unique_users","displayName":"Total","customComponent":"PercentBar","color":"#5BE0C7"},{"columnName":"rxBytes","displayName":"Rx User","customComponent":"PercentBar","format":"bytesFormat"},{"columnName":"txBytes","displayName":"Tx User","customComponent":"PercentBar","format":"bytesFormat"},{"columnName":"traffic","displayName":"User Traffic","customComponent":"PercentBar","format":"bytesFormat"},{"columnName":"manufacturer","displayName":"Manufacturer","hidden":true},{"columnName":"osType","displayName":"OS","hidden":true}]},"url":null,"id":17}',
             'recurse'  => true,
             'opts'     => OBJECT_MERGE_OPT_MERGE_ARRAY_VALUES | OBJECT_MERGE_OPT_UNIQUE_ARRAYS | OBJECT_MERGE_OPT_NULL_AS_UNDEFINED
-        ]
+        ],
     );
 
     /**
@@ -215,6 +225,7 @@ public function testObjectMerge()
                 $actual = object_merge(...$objects);
             }
             $this->assertEquals($expected, $actual);
+//            var_dump($actual);
         }
     }
 }