[11.x] Add before and after methods to Collection

[avosalmon]

This PR introduces two new methods to the Collection and LazyCollection.

before method

The before method returns the item before the given item. It returns null if the given item is the first item or not found.

$collection = collect([1, 2, 3, 4, 5, 'name' => 'taylor', 'framework' => 'laravel']);

$collection->before(2) // 1
$collection->before('taylor') // 5
$collection->before('laravel') // 'taylor'
$collection->before(fn ($value) => $value > 4) // 4
$collection->before(fn ($value) => ! is_numeric($value)) // 5
$collection->before(1) // null
$collection->before('not found') // null

after method

The after method returns the item after the given item. It returns null if the given item is the last item or not found.

$collection = collect([1, 2, 3, 4, 5, 'name' => 'taylor', 'framework' => 'laravel']);

$collection->after(1) // 2
$collection->after('taylor') // 'laravel'
$collection->after(fn ($value) => $value > 4) // 'taylor'
$collection->after(fn ($value) => ! is_numeric($value)) // 'laravel'
$collection->after('laravel') // null
$collection->after('not found') // null

[taylorotwell]

Interesting - when did you find yourself needing these methods?

[avosalmon]

@taylorotwell I needed these methods in a couple of scenarios.
For example, when I was building a page that displayed a single resource while allowing the user to navigate between the next and previous resources, I wrote something like this.

$previousItem = $items->get($items->search($currentItem) - 1);
$nextItem = $items->get($items->search($currentItem) + 1);

It can be written like this using the before and after methods.

$previousItem = $items->before($currentItem);
$nextItem = $items->after($currentItem);

Another use case was that I retrieved a previous date from a series of dates.

- $previousDate = $dates->get($dates->search($date) - 1);
- $nextDate = $dates->get($dates->search($date) + 1);
+ $previousDate = $dates->before($date);
+ $nextDate = $dates->after($date);

[chrislurty]

I'm a little late to the party here, but my interpretation of before and after would mean they would return the collection of items before/after the given item index, instead if just the adjacent item.

More aptly named functions would have been previous and next, which are the terms used in the original example.

$previousItem = $items->before($currentItem);
$nextItem = $items->after($currentItem);

should be :

$previousItem = $items->previous($currentItem);
$nextItem = $items->next($currentItem);