feat(support): onlyKeys and exceptKeys methods for manipulatesarray

[iamdadmin]

Suggested from #2092 - introduces convenience methods ->onlyKeys and ->exceptKeys for ManipulatesArray, and tests.

Usage examples from the test:

    public function test_only_keys(): void
    {
        $collection = arr([
            'first_name' => 'John',
            'last_name' => 'Doe',
            'age' => 42,
        ]);
        $current = $collection
            ->onlyKeys(['first_name', 'last_name'])
            ->toArray();
        $expected = [
            'first_name' => 'John',
            'last_name' => 'Doe',
        ];

        $this->assertSame($expected, $current);
    }

    public function test_except_keys(): void
    {
        $collection = arr([
            'first_name' => 'John',
            'last_name' => 'Doe',
            'age' => 42,
        ]);
        $current = $collection
            ->exceptKeys(['age'])
            ->toArray();
        $expected = [
            'first_name' => 'John',
            'last_name' => 'Doe',
        ];

        $this->assertSame($expected, $current);
    }

[innocenzi]

I like the methods, but not the names; I don't think generic method names are helpful and I'd like to see more specific ones.

These are essentially "filter" methods, so maybe with should be an update to the existing filter where it accepts an array, and without should be a new reject method?

[iamdadmin]

I like the methods, but not the names; I don't think generic method names are helpful and I'd like to see more specific ones.

These are essentially "filter" methods, so maybe with should be an update to the existing filter where it accepts an array, and without should be a new reject method?

Well, given that it’s using diffKeys and intersectKeys under the hood, how about withKeys and withoutKeys? Or alternatively onlyKeys and exceptKeys?

Filter I’m guessing already exists and will take a closure. Reject is fine but I think except or without fits it better?

Edit: yep, filter takes a closure, and the issue with having it accept either a closure or with functionality, is that a filter can be both positive, negative, and based on other criteria, where with is a positive filter only. So I suggest avoiding the clash with that and with array_filter as that implies that kind of functionality from it.

Edit 2: given the intent behind your suggestion and the possibly ambiguity of using with or without at all (especially as with is sometimes a reserved operator in programming languages), I refactored to onlyKeys and exceptKeys which I think makes it clear what it does, and what you need to pass (i.e. 'keys').

[xHeaven]

Y'all are going to hate me, but I'd love to be able to pass Closures to these methods.

[iamdadmin]

Y'all are going to hate me, but I'd love to be able to pass Closures to these methods.

I’d say that’s what the filter method is for. It takes a closure and performs whatever filter you want, negative, positive, or arbitrary logic.

[brendt]

I’d say that’s what the filter method is for. It takes a closure and performs whatever filter you want, negative, positive, or arbitrary logic.

Agree.

Naming is hard 😅 I think there should be proper symmetry:

• with and without is the simplest, though a bit implicit that it works on keys
• withKeys and withoutKeys is more explicit, but also more verbose
• includeKeys and excludeKeys — just another idea
• include and exclude — probably too generic

tbh my preference is with and without, since the parameter name will make it clear that we're talking about keys.