[Proposal]: Additional array transformations when using partritioning or type comparison

[stloyd]

Describe the Proposal

I have noticed that when using partitioning, sorting, or type comparison, there are additional calls to array merge, array unpack, etc. This is done cause some methods have both normal variables and variadic ones.

I.e.:

public function partitionBy(string|Reference $entry, string|Reference ...$entries) : self

But later on, those two are merged into one, which is not really needed, as a variadic variable can handle that well already.

API Adjustments

public function partitionBy(string|Reference ...$entries) : self

Are you intending to also work on proposed change?

Yes

Are you interested in sponsoring this change?

None

Integration & Dependencies

No response

[norberttech]

This one is intentional:

public function partitionBy(string|Reference $entry, string|Reference ...$entries) : self

makes mandatory to pass at least one entry.

public function partitionBy(string|Reference ...$entries) : self

This one would require an exception that at least one entry is required.

[stloyd]

What about going down the road and preventing empty references (which in the end is what all those try to create):

final class References implements \ArrayAccess, \Countable, \IteratorAggregate
{
    /**
     * @var array<string, Reference>
     */
    private array $refs = [];

    /**
     * @var array<string, true>
     */
    private array $without = [];

    public function __construct(string|Reference ...$references)
    {
        if ([] === $references) {
            throw new InvalidArgumentException('References cannot be empty.');
        }

[norberttech]

I think it's a much better DX when you know upfront, looking at the method definition that at least one reference is required than finding out in the runtime that your code is broken.

public function partitionBy(string|Reference $entry, string|Reference ...$entries) : self - helps also static analysis tools, which knows right a way that at least one is needed just like php linter.

I would prefer to keep it this way, but maybe create an ADR for that - I can make LLM to turn conversation into an ADR (feel free to do it as well)