/**
* descend inside an array, using dot.notation.support, and optionally
* extending the array if the end of the dot.notation.path is missing
*
* @param array &$arr
* the array to dig into
* @param string $index
* the dot.notation.support path to descend
* @param array|callable|string|null $extendingItem
* if we need to extend, what data type do we extend using?
* @return mixed
*/
public static function &intoArray(&$arr, $index, $extendingItem = null)
{
// robustness!
RequireIndexable::check($arr, E4xx_UnsupportedType::class);
$retval =& self::getPathFromRoot($arr, $index, $extendingItem);
return $retval;
}
/**
* merge their array into our array
*
* @param array &$ours
* the array that we want to merge into
* @param array|Traversable $theirs
* the array that we want to merge from
* @return void
*/
public static function fromArray(&$ours, $theirs)
{
// robustness!
RequireIndexable::check($ours, E4xx_UnsupportedType::class);
RequireTraversable::check($theirs, E4xx_UnsupportedType::class);
// copy from them to us
foreach ($theirs as $key => $value) {
self::mergeKeyIntoArray($ours, $key, $value);
}
// all done
}
/**
* merge their data into our array, using dot.notation.support to
* find the point where the merge starts
*
* @param array &$arr
* the array that we want to merge into
* @param string $path
* the dot.notation.support path to where the merge should start
* @param mixed $value
* the data that we want to merge from
* @param array|callable|string|null
* if $path goes beyond what exists in $ours, how do we want to
* extend $ours?
* @return void
*/
public static function intoArray(&$arr, $path, $value, $extendingItem = null)
{
// robustness!
RequireIndexable::check($arr, E4xx_UnsupportedType::class);
RequireDotNotationPath::check($path);
// find the point where we want to merge
list($firstPart, $finalPart) = self::splitPathInTwo($path);
if ($firstPart !== null) {
$leaf =& DescendDotNotationPath::intoArray($arr, $firstPart, $extendingItem);
} else {
$leaf =& $arr;
}
// merge it
MergeIntoProperty::of($leaf, $finalPart, $value);
}
/**
* merge their data into one of our array's properties
*
* @param array &$arr
* the array that we want to merge into
* @param string $property
* the property to merge into
* @param mixed $value
* the data that we want to merge from
* @return void
*/
public static function ofArray(&$arr, $property, $value)
{
// robustness!
RequireIndexable::check($arr, E4xx_UnsupportedType::class);
// easiest case - no clash
if (ShouldOverwrite::intoArray($arr, $property, $value)) {
$arr[$property] = $value;
return;
}
// special case - we are merging into an object
if (is_object($arr[$property])) {
MergeIntoAssignable::from($arr[$property], $value);
return;
}
// if we get here, then we must be merging into an array
MergeIntoIndexable::from($arr[$property], $value);
}
/**
* @covers ::check
* @covers ::checkMixed
* @dataProvider provideNonIndexables
* @expectedException GanbaroDigital\Reflection\Exceptions\E4xx_UnsupportedType
*/
public function testRejectsNonIndexablesWhenCalledStatically($item)
{
// ----------------------------------------------------------------
// setup your test
// ----------------------------------------------------------------
// perform the change
RequireIndexable::check($item);
}
/**
* does $path point to a valid piece of data inside $container?
*
* @param array $container
* the container to look inside
* @param string $path
* the dot.notation.support path to walk
* @return boolean
* TRUE if $path points to a vlaid piece of data
* FALSE otherwise
*/
public static function inArray($container, $path)
{
// defensive programming!
RequireIndexable::check($container, E4xx_UnsupportedType::class);
RequireAnyOneOf::check([new IsDotNotationPath(), new IsStringy()], [$path], E4xx_NotDotNotationPath::class);
try {
DescendDotNotationPath::intoArray($container, $path);
return true;
} catch (E4xx_NoSuchIndex $e) {
return false;
} catch (E4xx_NoSuchProperty $e) {
return false;
}
}
/**
* extract a value from an array, using dot.notation.support
*
* @param array $arr
* the array to extract from
* @param string $index
* the dot.notation.support path to walk
* @return mixed
* whatever we find when we walk the path
*/
public static function fromArray($arr, $index)
{
// robustness!
RequireIndexable::check($arr, E4xx_UnsupportedType::class);
return DescendDotNotationPath::intoArray($arr, $index);
}
