Laravel 5 Collections: Executing a Function on a Collection and Returning the Function Results With pipe

The pipe method is similar to the tap method in that it executes the provided $callback function on a copy of the collection; however, unlike the tap method, the pipe method returns the result of the callback function.

#Signature

1public function pipe(
2    callable $callback
3);

#Example Use

The following example demonstrates the basic usage of the pipe helper method, notice that we receive a copy of the collection to the pipe method's callback argument; the returned result is the return value of the callback function:

1$medianValue = collect([10, 20, 30])->
2                pipe(function ($collection) {
3                    return $collection->median();
4                });

After the above code has executed, the $medianValue would be 20. However, we can do even more interesting things with the pipe method. In the following example, we will look at a simple way to retrieve a weather forecast from the Yahoo Weather API from a collection of locations. Within the pipe method callback function, we will gather the weather forecasts and then return a new collection instance with the locations and forecasts.

Simple Weather Forecast Implementation using pipe:

 1/**
 2 * Gets the weather forecasts for the given locations.
 3 *
 4 * @param \Traversable $locations
 5 * @return Illuminate\Support\Collection
 6 */
 7function getForecasts($locations) {
 8    return Collection::wrap($locations)
 9    ->pipe(function ($places) {
10        // Collection to hold our forecasts.
11        $forecasts = collect([]);
12 
13        $places->each(function ($place)
14                      use (&$forecasts)) {
15 
16        $apiUrl = 'https://query.yahooapis.com/v1/' .
17                  'public/yql?q=select%20*%20from%20' .
18                  'weather.forecast%20where%20woeid%20' .
19                  'in%20(select%20woeid%20from%20 ' .
20                  'geo.places(1)%20where%20text%3D%22' .
21                  '<PLACE>%22)&format=json&env=store' .
22                  '%3A%2F%2Fdatatables.org%2' .
23                  'Falltableswithkeys';
24 
25        $apiUrl = str_replace('<PLACE>', $place, $apiUrl);
26 
27        $forecast = with(new GuzzleHttp\Client,
28                         function ($client) use ($apiUrl) {
29            /** @var GuzzleHttp\Client $client */
30            $response = $client->get($apiUrl);
31            $responseBody = $response->getBody();
32            $result = json_decode(
33                        $responseBody->getContents()
34                      );
35 
36            return transform(
37                    $result->query->results,
38                    function ($results) {
39                        return collect($results->channel
40                                       ->item->forecast);
41                }, function ($results) {
42                    return collect();
43                });
44        });
45 
46        $forecasts[$place] = $forecast;
47    });
48 
49        return $forecasts;
50    });
51}

After defining the getForecasts function, we can then use it like so:

1$forecasts = getForecasts([
2    'San Francisco, CA',
3    'Paris, France'
4]);

After the above code has executed, the $forecasts variable would contain a collection of collections with each locations forecast, if available.

∎