refactor(groupbyable)!: simplify implementation and update typing info

[Lctrs]

This PR:

• Simplify GroupBy implementations to ease use
• Fix GroupByable operations static analysis
• It breaks backward compatibility
• Has unit tests (phpspec)
• Has static analysis tests (psalm, phpstan)

Follows #206.
Closes #206.

[drupol]

Thanks looks good overall !!!

I'll do a in-depth review tonight.

[drupol]

In overall, I'm ok with this PR, it was something that I had in mind, but somehow I was always bouncing it back to the bottom of the tasks list.

There is one thing that needs to be done, is to update the documentation API (api.rst), there is not that much to do:

1. Update the groupBy signature
2. Add comprehensive code examples in a sample code file

[drupol]

LGTM, I'll wait a bit so @AlexandruGG can make same feedback, if not, I'll merge it on Monday.

[AlexandruGG]

I like the simplification, thank you @Lctrs!

Please see the comments however, I think we are potentially introducing a bug if we remove the handling of null values from the callback

[AlexandruGG]

I think the only way to prevent non-null values for NewTKey is to restrict the type of key that can be used here. For example:

@template NewTKey of array-key
@template NewTKey of int|string

It's not ideal because Collection supports using anything as a key due to Generators. So I think the alternative is to just make sure to handle null properly in the implementation

[drupol]

I noticed this thing, but I was more keen to let user provide a valid callback.

If the user provide an invalid callback, then the user will get an invalid return.

Maybe we could also improve the operation documentation for that ?

[AlexandruGG]

The issue is that nothing in the function signature tells me that null is invalid there. So in that case I will assume it's supported.

The way I see it, there are a few choices here:

1. Continue supporting it like in the current implementation
2. Don't support it by updating the type annotations to disallow it
3. Don't support it by throwing an exception, but leaving the type annotations as they are so as to allow any key type
4. Don't support it by returning an unexpected result

Currently we are doing option 4 which I think is the worst out of these from the user experience perspective

[drupol]

Fair enough, you're right.

Here's my thoughts:

• Option 1: We might end up with an ugly implementation - like the current one on master branch,
• Option 2: I like this idea, but how would you do that?
• Option 3: I also like this idea,
• Option 4: disqualified!

@Lctrs WDYT ? What's your point of view?

[Lctrs]

Option 2 is the best. But since it's not possible, it will be option 3.

[drupol]

Yes! This is how I would have implemented it.

Now that I'm reading it, should we also check that the returned value is either int|string ?

WDYT ?

[Lctrs]

Ooooh that's right. We're working with arrays here. We could just go with @AlexandruGG first proposition here (ie. @template NewTKey of array-key). We could then widen the possible types later if someone comes with an algo that allows to work with iterable compatible key types.

[drupol]

Oh that's even better !!!

[Lctrs]

Done.

[drupol]

Good for me.

Let's wait for @AlexandruGG 's feedback as he was the initiator of the request.

[AlexandruGG]

Nice one, thank you for the good work here @Lctrs 💯

[drupol]

Thanks indeed :)

[drupol]

This feature is now shipped in version 6.0.0 ! Congrats for your contribution @Lctrs !