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.
∎