Proposal: collect([])->rescue

[henzeb]

Imagine you are processing a (large) array, or working with a generator that on each record does a HTTP call or something that may fail. Normally looping through an array or collection that at some point throws an exception, ends the array, even if run within rescue(). This would mean you have to start all over again, just to get to the rest. But what if you could rescue that single item and continue where you left off?

For this I propose a rescue method on Collection and LazyCollection:

Given the following collection:

$collection = collect(
    [
        1 => fn() => 'hello 1',
        2 => fn() => throw new Exception('hello 2'),
        3 => fn() => 'hello 3',
    ]
);

The following would fail:

$collection->map(fn(callable $callback) => $callback);

Of course: you could write it like this:

$collection->map(fn(callable $callback) => rescue($callback));

The above would work, but if you have to do more than just executing a callback, you would get a closure in a closure and it would become unreadable very quickly.

The following is much more readable. It would return the closure in case of an exception:

$collection->rescue->map(fn(callable $callback) => $callback);

The reason of this is because under the hood you have to use map, otherwise values wouldn't be modified on the returned collection, and a failed tap call would otherwise return a collection with the second item null, which is undesirable. If you need it to return null, one could easily do the following:

$collection->rescue(
    function(Collection $collection) {
        return $collection->map(fn(callable $callback) => $callback);
    },
   fn()=>null
);

This might quickly become unreadable again, so I was thinking of a second method called rescueWith.

$collection->rescueWith(fn()=>null)
           ->map(fn(callable $callback)=>$callback);

The problem with this is that in order to do that, it needs to return a HigherOrderCollectionProxy, which must be able to pass along additional parameters to the Higher Order method. The current implementation does not do that, and the only viable way without modifying that class is by abusing Cache or Config or an Anonymous class which extends the proxy class. If someone has a better solution, please let me know.

The following would be the implementation. In rescueWith I have an Anonymous Class extending HigherOrderCollectionProxy to demonstrate the most viable idea, next to altering the original proxy class.

use Illuminate\Support\Collection;
use Illuminate\Support\HigherOrderCollectionProxy;
use Illuminate\Support\LazyCollection;

class CollectionRescueMixin
{
    public function __construct()
    {
    }

    public function rescue(): Closure
    {
        return fn(callable $callback, $rescue = null, $report = true): LazyCollection|Collection => $this->map(
            fn($item) => rescue(
                fn() => $callback(Collection::make([$item]))->first(),
                fn($e) => value($rescue ?? fn() => $item, $e, $item),
                $report
            )
        );
    }

    public function rescueWith(): Closure
    {
        return fn($rescue = null, $report = true): HigherOrderCollectionProxy => new class
            ($this, 'rescue', $rescue, $report) extends HigherOrderCollectionProxy {
                private array $parameters;
    
                public function __construct($collection, $method, ...$parameters)
                {
                    $this->parameters = $parameters;
                    parent::__construct($collection, $method);
                }
    
                public function __call($method, $parameters)
                {
                    return $this->collection->{$this->method}(
                        fn($value) => $value->{$method}(...$parameters),
                        ...$this->parameters
                    );
                }
        };
    }
}

Collection::mixin(new CollectionRescueMixin());
LazyCollection::mixin(new CollectionRescueMixin());
Collection::proxy('rescue');
LazyCollection::proxy('rescue');

Let me know what you guys think.