Add first() and last() functions to Collection

[baijunyao]

No description provided.

[richardm-stripe]

Hi @baijunyao, thank you for the pull request. I think these methods could be useful, but I suggested some modifications to the docstring to clarify that they operate on the current page, not the collection. Does this make sense to you?

[baijunyao]

@richardm-stripe I agree, thank you very much.

[richardm-stripe]

Hi @baijunyao, still thinking about this.

I'm a little uneasy about using \end for ->last() and \reset for ->first() since they mutate.

That is, if somebody did

$custs = $stripe->customers->all(['limit' => 5]);

\next($custs->data);
var_dump(\current($custs->data)->id); // Customer 2
var_dump($custs->first()); // Customer 1
var_dump(\current($cs->data)->id); // Customer 1

They might expect this to print "Customer 2, Customer 1, Customer 2" but this will actually print "Customer 2, Customer 1, Customer 1".

(This is sort of contrived, but a scenario like this could matter especially if some of these calls were hidden inside some user's helper functions).

What do you think about implementing as \count($this->data) > 0 ? $this->data[0] : false and \count($this->data) > 0 ? $this->data[\count($this->data) - 1] : false, instead?

[baijunyao]

You're right, but there may still be problems.

public function first()
{
    return \count($this->data) > 0 ? $this->data[0] : false;
}

$custs = $stripe->customers->all(['limit' => 5]);

unset($collection->data[0]);

var_dump($custs->first()); // Undefined offset: 0

So what do you think of changing to the following way?

public function first()
{
    foreach ($this->data as $item) {
        return $item;
    }

    return false;
}

public function last()
{
    foreach (array_reverse($this->data, true) as $item) {
        return $item;
    }

    return false;
}

And If $this->data is empty, is it better to return null than false?

[richardm-stripe]

Hi @baijunyao, sorry for the delay. I do agree null is better than false.

I don't think Undefined offset: 0 is necessarily unexpected after calling unset, and array_reverse seems like it's doing more work than it should to navigate to the last (set) index. I think I still prefer \count($this->data) > 0 ? $this->data[0] : null.

[baijunyao]

Never mind.
Okay, I updated the code.
Thanks.

[ctrudeau-stripe]

LGTM. Thank you @baijunyao

[richardm-stripe]

(This was released in v7.44.0. Thank you again @baijunyao for the contribution)