public static function embedInto(
        array $items,
        string $fieldName,
        array $destination = [],
        bool $overwrite = false
    ) : array {
        foreach ($items as $key => $item) {
            if (!array_key_exists($key, $destination)) {
                $destination[$key] = [$fieldName => $item];
                continue;
            }

            self::ensureIsArray($destination[$key], 'a value in $destination was not an array');

            if (!$overwrite && array_key_exists($fieldName, $destination[$key])) {
                throw new \Exception('$fieldName key already exists in a $destination array');
            }

            $destination[$key][$fieldName] = $item;
        }

        return $destination;
    }
public static function embedInto(
        array $items,
        string $fieldName,
        array $destination = [],
        bool $overwrite = false
    ) : array {
        foreach ($items as $key => $item) {
            if (!array_key_exists($key, $destination)) {
                $destination[$key] = [$fieldName => $item];
                continue;
            }

            self::ensureIsArray($destination[$key], 'a value in $destination was not an array');

            if (!$overwrite && array_key_exists($fieldName, $destination[$key])) {
                throw new \Exception('$fieldName key already exists in a $destination array');
            }

            $destination[$key][$fieldName] = $item;
        }

        return $destination;
    }
public static function embedInto ( array $ items , string $ fieldName , array $ destination = [ ] , bool $ overwrite = false ) : array { foreach ( $ items as $ key => $ item ) { if ( ! array_key_exists ( $ key , $ destination ) ) { $ destination [ $ key ] = [ $ fieldName => $ item ] ; continue ; } self :: ensureIsArray ( $ destination [ $ key ] , 'a value in $destination was not an array' ) ; if ( ! $ overwrite && array_key_exists ( $ fieldName , $ destination [ $ key ] ) ) { throw new \ Exception ( '$fieldName key already exists in a $destination array' ) ; } $ destination [ $ key ] [ $ fieldName ] = $ item ; } return $ destination ; }
Takes each item and embeds it into the destination array, returning the result.

Each item's key is used as the key in the destination array so that keys are preserved.  Each resulting item in
the destination will be embedded into a field named by $fieldName.  Any items that don't have an entry in
destination already will be added, not skipped.

For example, embedInto(['Joe', 'Sue'], 'lastName', [['firstName' => 'Billy'], ['firstName' => 'Bobby']]) will
return [['firstName' => 'Billy', 'lastName' => 'Joe'], ['firstName' => 'Bobby', 'lastName' => 'Sue']]

@param array $items The items to embed into the result.
@param string $fieldName The name of the field to embed the items into.  This field must not exist in the
destination items already.
@param array $destination An optional array of arrays to embed the items into.  If this is not provided then
empty records are assumed and the new record will be created only containing
$fieldName.
@param bool $overwrite whether to overwrite $fieldName in $destination array

@return array $destination, with all items in $items added using their keys, but underneath a nested $fieldName
key.

@throws \InvalidArgumentException if $fieldName was not a string
@throws \InvalidArgumentException if a value in $destination was not an array
@throws \Exception if $fieldName key already exists in a $destination array
Takes each item and embeds it into the destination array returning the result .