Proposition of new helper method: Arr::groupBy

[raveren]

Hello, beautiful community!

I've been using this small helper for years and I thought it's elegant (and resembles magic) enough to be considered to become part of core Laravel:

/**
 * Build a hierarchical structure out of a typical "results" array.
 *
 * Input example:
 *      ['columnA' => 1, 'columnB' => 2, 'columnC' => 3],
 *      ['columnA' => 4, 'columnB' => 5, 'columnC' => 6],
 *
 * Format examples:
 *      columnA=>columnB                                 // great for drop-downs!
 *          [1=>2, 4=>5]
 *      columnA=>*
 *          [1=>[1,2,3], 4=>[4,5,6]]
 *      columnA=>columnB,columnC                        // it's like a multidimensional `pluck`!
 *          [1=>[2,3], 4=>[5,6]]
 *      columnA[]=>*                                    // when there's no unique column
 *          [1=>[[1,2,3],], 4=>[[4,5,6],]]
 *      columnA[columnC]=>*
 *          [1[3]=>[1,2,3], 4[6] =>[4,5,6]
 *      columnA[columnC][]=>columnB,columnA             // go nuts!
 *          [1[3]=>[[2,1]], 4[6] => [[5,4]]]
 *
 * For the more advanced examples @see HelperTest::test_make_tree()
 */
function arrayGroupBy(array|ArrayAccess $array, string $format): array
{
    preg_match('#(?<key>[^=\[]+)(?<braces>(?:\[[^]]*])*)=>(?<columns>.+)#', $format, $matches);

    if (count($matches) < 4) {
        throw new LogicException('Invalid format pattern: ' . $format);
    }

    // For most complex case: key1[key2][key3][]=>key4,key5
    $key     = $matches['key'];     // key1
    $braces  = $matches['braces'];  // [key2][key3][]
    $columns = $matches['columns']; // key4,key5

    if ($braces) {
        // '[key2][key3][]' => [ 'key2', 'key3', '' ]
        preg_match_all('#\[([^]]*)]#', $braces, $matches);
        $nestedKeys = $matches[1];
    }

    $values = $columns === '*'
        ? '*'
        : explode(',', $columns);

    $hasMultipleValues = $values === '*' || count($values) > 1;

    $result = [];
    foreach ($array as $row) {
        $newLeaves = null;

        if ($hasMultipleValues) {
            if ($values === '*') {
                $newLeaves = $row;
            } else {
                foreach ($values as $v) {
                    $newLeaves[$v] = $row[$v];
                }
            }
        } else {
            $newLeaves = $row[$columns];
        }

        // The '[key2][key3][]' part
        if ($braces) {
            $result[$row[$key]] ??= [];

            $pointer = &$result[$row[$key]];

            // we are going *deeper*
            foreach ($nestedKeys as $nestedKey) {
                if ($nestedKey) {
                    $pointer[$row[$nestedKey]] ??= [];
                    $pointer                   = &$pointer[$row[$nestedKey]];
                } else { // []
                    $pointer[] = [];
                    $pointer   = &$pointer[array_key_last($pointer)];
                }
            }

            $pointer = $newLeaves;
        } else {
            $result[$row[$key]] = $newLeaves;
        }
    }

    return $result;
}

test, with more examples:

public function test_group_array_by(): void
{
    $arr = [
        ['id' => 1, 'name' => 'name1', 'more_data' => true,],
        ['id' => 2, 'name' => 'name2', 'more_data' => true,],
        ['id' => -1, 'name' => 'name-1', 'more_data' => 'cat.',],
        ['id' => 4, 'name' => 'name4', 'more_data' => true,],
        ['id' => 22, 'name' => 'name22', 'more_data' => false,],
    ];

    $format = 'id=>*';
    self::assertEquals(
        [
            1  => ['id' => 1, 'name' => 'name1', 'more_data' => true],
            2  => ['id' => 2, 'name' => 'name2', 'more_data' => true],
            -1 => ['id' => -1, 'name' => 'name-1', 'more_data' => 'cat.'],
            4  => ['id' => 4, 'name' => 'name4', 'more_data' => true],
            22 => ['id' => 22, 'name' => 'name22', 'more_data' => false],
        ],
        arrayGroupBy($arr, $format)
    );

    $format = 'name=>*';
    self::assertEquals(
        [
            'name1'  => ['id' => 1, 'name' => 'name1', 'more_data' => true],
            'name2'  => ['id' => 2, 'name' => 'name2', 'more_data' => true],
            'name-1' => ['id' => -1, 'name' => 'name-1', 'more_data' => 'cat.'],
            'name4'  => ['id' => 4, 'name' => 'name4', 'more_data' => true],
            'name22' => ['id' => 22, 'name' => 'name22', 'more_data' => false],
        ],
        arrayGroupBy($arr, $format)
    );

    $format = 'id=>name';
    self::assertEquals(
        [
            1  => 'name1',
            2  => 'name2',
            -1 => 'name-1',
            4  => 'name4',
            22 => 'name22',
        ],
        arrayGroupBy($arr, $format)
    );

    // id=>id
    $format = 'id=>id';
    self::assertEquals(
        [1 => 1, 2 => 2, -1 => -1, 4 => 4, 22 => 22],
        arrayGroupBy($arr, $format)
    );

    $format = 'id=>id,name';
    self::assertEquals(
        [
            1  => ['id' => 1, 'name' => 'name1'],
            2  => ['id' => 2, 'name' => 'name2'],
            -1 => ['id' => -1, 'name' => 'name-1'],
            4  => ['id' => 4, 'name' => 'name4'],
            22 => ['id' => 22, 'name' => 'name22'],
        ],
        arrayGroupBy(collect($arr), $format)
    );

    //
    // multi-level
    //
    $arr = [
        ['id' => 10, 'name' => 'name1'],
        ['id' => 11, 'name' => '[[ SAME NAME ]]'],
        ['id' => 12, 'name' => '[[ SAME NAME ]]'],
    ];

    $format = 'name[]=>id,name';
    self::assertEquals(
        [
            'name1'           => [
                ['id' => 10, 'name' => 'name1'],
            ],
            '[[ SAME NAME ]]' => [
                ['id' => 11, 'name' => '[[ SAME NAME ]]'],
                ['id' => 12, 'name' => '[[ SAME NAME ]]'],
            ],
        ],
        arrayGroupBy($arr, $format)
    );

    $format = 'name[id]=>id,name';
    self::assertEquals(
        [
            'name1'           => [
                10 => ['id' => 10, 'name' => 'name1'],
            ],
            '[[ SAME NAME ]]' => [
                11 => ['id' => 11, 'name' => '[[ SAME NAME ]]'],
                12 => ['id' => 12, 'name' => '[[ SAME NAME ]]'],
            ],
        ],
        arrayGroupBy($arr, $format)
    );

    // this is getting bonkers!
    $format = 'name[id][]=>*';
    self::assertEquals(
        [
            'name1'           => [
                10 => [
                    0 => ['id' => 10, 'name' => 'name1'],
                ],
            ],
            '[[ SAME NAME ]]' => [
                11 => [0 => ['id' => 11, 'name' => '[[ SAME NAME ]]']],
                12 => [0 => ['id' => 12, 'name' => '[[ SAME NAME ]]']],
            ],
        ],
        arrayGroupBy($arr, $format)
    );
}

Did it click in your brain? Do you like it?

I find the pattern satisfyingly self-explanatory, intuitive and it creates predictable results.

Do you think it worth doing a PR?

[henzeb]

Could you rather use the code from Collection? This already has a group by. Otherwise you'd have redundant code.

[raveren]

Ooh, thanks for the heads up.

I'll attempt then to merge my functionality with the existing one in Collection.

[mikeydevelops]

@raveren you can copy the groupBy method from Collection to Arr and just change the implementation in Collection to use the Arr method like many other methods in Collections do.