Add Nette\Utils\Collection

[milo]

• bug fix? no
• new feature? yes
• BC break? no
• doc PR: will

I'm using this abstract collection really often. Its purpose is to emulate typed array in most cases.

May seem to be strange that methods like get() or add() are missing. It is because of PHP invariance limitation.

An example of basic usage:

# One item for collection
class Person
{
    public $email;
    public $firstName;
    public $lastname;
    public $username;
}

# Collection itself
class People extends Nette\Utils\Collection
{
    public function add(Person $person): People
    {
        $this->addItem($person, $person->username);
        return $this;
    }

    public function get(string $username): Person
    {
        return $this->getItem($username);
    }
}


# Creating collection
$people = People::fromIterator(...);

# If good friend Joe is here...
if ($people->has('joe')) {
	debug("Joe is here... again.");
}


# Example usage: create an array of emails, only if email is set
$emails = $people->convert(function (Person $person, $key, & $unset) {
	$unset = $person->email === NULL;
	return $person->email;
});

Collection can declare frequent helpers on self:

# Sorting example
public function sortDefault()
{
	$this->sortBy(function (Person $a, Person $b) {
		if ($a->username === 'joe') return -1;  # sorry joe
		return $a->username <=> $b->username;
	});
}

# Coversion to array for Form <select> input
public function forSelectInput()
{
	return $this->convert(function (Person $person) {
		return "$person->lastname $person->firstName";
	});
}

And usage as typed array:

class Mailer
{
	public function mail(People $people, Mail $message)
	{
		$people->walk(function (Person $person) use ($message) {
			$this->senfTo($person->email, $message);
		});
	}
}

The IteratorAggreagete is here for ordinary loops, like:

/** @var People|Person[] $people */
$people = ...;
foreach ($people as $person) {

)

The ArrayAccess is not implemented. I tried that, but never found it useful.

The normalizeKey() method can convert complex types to scalar, for example for multi column primary keys in database. On the other hand, I overloaded it very rarely.

If this would be accepted, I'll add tests and doc.

[Majkl578]

From the user's point of view, why would/should one use this, compared e.g. to doctrine/collections (which are even more generic and actually behave like array thanks to ArrayAccess)?

[milo]

@dg Rebased

@Majkl578 I don't use doctrine collections, but when I take a look at source...

My collections used to look very similarly. Problem arises when you want to be strict on types. You cannot change the get($key) or add($element) signature. So you have to do something like:

public function add($element)
{
    if (!$element instanceof Person) throw ...
}

ArrayAccess is a very small part of "behave like array". May seem usable, but consider:

$people[$person->username] = $person;
# vs.
$people->add($person);

$people[$person->username]
# vs.
$people->get($person->username)

unset($person[$person->username])
# vs.
# not implemented, I don't remove items one by one, usually by filter only

And sometimes, IDE has a problem with "napovídání" (mi vypadl anglický termín) with ArrayAccess.

[JanTvrdik]

I don't think this belongs to nette/utils.

[milo]

@JanTvrdik Partially agree. The best would be native typed arrays in the PHP itself.

Collection is a typical part of a model layer, Nette does not have such. This is helper only without big ambitions.

Real world example how I use it:

return People::fromIterator(
    $this->dibi->query('...')->setRowClass(Person::class)
);

But not just database. In one project, I'm listing firewall rules from router:

$rules = new Firewall\Rules;
foreach ($this->switch->command(.....) as $line) {
    $rules->add(Firewall\Rule::fromCliFormat($line));
}

The point is, that working with typehint People is much more efficient and safe than working with array and @var Person[] annotation.

Btw. there used to be Collections in Nette, but this is different.

[milo]

Since its WIP, rebased to some old commit.