[12.x] Add Collection::containsManyItems() method

[stevebauman]

This PR adds the containsManyItems method to collections, like the containsOneItem method that already exists.

This assists in keeping a uniform syntax in situations where you need to take a code path depending on the collection being empty, having one item, or having many:

match (true) {
    $collection->isEmpty() => '...',
    $collection->containsOneItem() => '...',
    $collection->containsManyItems() => '...',
};

[cosmastech]

If the goal here is to just see if there are at least two items in the collection matching the filter, wouldn't it be better to call each() and then break the loop once you've met the limit of 2?

[stevebauman]

This is basically identical to the existing containsOneItem method to maintain consistency between the two:

framework/src/Illuminate/Collections/Collection.php

Lines 729 to 736 in cc03bd4

	public function containsOneItem(?callable $callback = null): bool
	{
	if ($callback) {
	return $this->filter($callback)->count() === 1;
	}
	return $this->count() === 1;
	}

[shaedrich]

I wonder if it would make sense to add an assertion here and in the two corresponding methods

Suggested change

	* @return bool
	* @return bool
	* @phpstan-assert-if-true non-empty-array<TKey, TValue> $this->items

[stevebauman]

I followed suit with the containsOneItem method doc block:

framework/src/Illuminate/Collections/Collection.php

Lines 723 to 736 in cc03bd4

	/**
	* Determine if the collection contains exactly one item. If a callback is provided, determine if exactly one item matches the condition.
	*
	* @param (callable(TValue, TKey): bool)|null $callback
	* @return bool
	*/
	public function containsOneItem(?callable $callback = null): bool
	{
	if ($callback) {
	return $this->filter($callback)->count() === 1;
	}
	return $this->count() === 1;
	}

[shaedrich]

Nobody said, there wasn't room for improvement. With this argument, we'd be stuck in the stone age forever.

[stevebauman]

lol easy -- its a doc block

[shaedrich]

It's more than a comment. It improves static analysis.