Laravel Miscellaneous Helper Function: tap

tap($value, $callback)

The tap helper function is used to call a given Closure (provided as an argument to the $callback parameter) with the given $value. The tap helper function will return the reference to the original $value as its return value. This allows you to call any number of methods with any type of return values within the $callback while maintaining a reference to the original object. This behavior is particularly useful during method chaining. Another way to think of this functions behavior is that it allows you to specify and fix the return value of a series of method calls, regardless of what methods are called within the internal block.

The following example PHP classes will be used to demonstrate a trivial usage of the tap helper function. The classes represent a crude "talker" system where one can add messages and retrieve the final message back:

Stored in the app/Message.php file:

 1<?php
 2 
 3namespace App;
 4 
 5class Message
 6{
 7 
 8    /**
 9     * The actual message.
10     *
11     * @var string
12     */
13    protected $message = '';
14 
15    /**
16     * Gets the original message.
17     *
18     * @return string
19     */
20    public function getOriginal()
21    {
22        return $this->message;
23    }
24 
25    /**
26     * Changes the message.
27     *
28     * @param  $message
29     * @return Message
30     */
31    public function change($message)
32    {
33        $this->message = $message;
34 
35        return $this;
36    }
37 
38    public function __toString()
39    {
40        return strtolower($this->message);
41    }
42 
43}

The Message class if fairly simple. It is simply a value object that wraps PHP's native string data type. It provides a few methods that can be used to retrieve the original value and change (mutate) the internal value of the message. When the message is cast back to a string it is converted to its lower cased variant. The important thing to notice is that the change method returns a reference back to itself.

Stored in the app/Talker.php file:

 1<?php
 2 
 3namespace App;
 4 
 5class Talker
 6{
 7 
 8    /**
 9    * The actual parts of the message.
10    *
11    * @var array
12    */
13    protected $messageParts = [];
14 
15    /**
16     * Adds a message part to the end of the message.
17     *
18     * @param  $message
19     * @return Message
20     */
21    public function atEnd(Message $message)
22    {
23        array_push($this->messageParts, $message);
24        return $message;
25    }
26 
27    /**
28     * Adds a message part to the start of the message.
29     *
30     * @param  $message
31     * @return Message
32     */
33    public function atBeginning(Message $message)
34    {
35        array_unshift($this->messageParts, $message);
36        return $message;
37    }
38 
39    /**
40     * Returns the string representation of the message.
41     *
42     * @return string
43     */
44    public function talk()
45    {
46        return ucfirst(implode(' ', $this->messageParts));
47    }
48 
49}

The Talker class is also very simple. It maintains an array of Message instances and allows you to add them to either the beginning or ending of the array of messages. In addition, it allows you to retrieve a string made up of all the individual messages with the first character upper cased. Annoyingly the atEnd and atBeginning methods return the Message instance instead of the Talker instance, which makes chaining rather difficult.

The following example will create a simple helper function to remove some of the steps of using the Talker and Message APIs:

 1<?php
 2 
 3use App\Talker;
 4use App\Message;
 5 
 6/**
 7 * Say something.
 8 *
 9 * string  $message
10 * @return string
11 */
12function saySomething($message) {
13    $talker = new Talker;
14    $talker->atBeginning(new Message)->change($message);
15    return $talker->talk();
16}

Using the new helper function might look like this:

1<?php
2 
3echo saySomething('Hello World');

The user would see the following text in the browser:

1Hello world

It would be nice if we could return the value of the method chain from our function like so:

 1<?php
 2 
 3// ...
 4 
 5function saySomething($message) {
 6    $talker = new Talker;
 7    return $talker->atBeginning(new Message)->change($message)->talk();
 8}
 9 
10// ...

However, that code would not work. This is because the atBeginning method on the Talker class returns an instance of Message. The talk method does not exist on the Message class, and if it did would probably not have the same behavior as the Talker instance method. We can use the tap function to get around this quite easily:

 1<?php
 2 
 3// ...
 4 
 5function saySomething($message) {
 6    $talker = new Talker;
 7    return tap($talker, function($t) use ($message) {
 8        $t->atBeginning(new Message)->change($message);
 9    })->talk();
10}
11 
12// ...

#Tap Function Closure Arguments

In the previous example the Closure defines a parameter named $t. When the tap function executes, the value of $talker will be used as the inner value of $t and they will refer to the same Talker instance. The following diagram visually demonstrates the flow of data in the tap helper function.

In the above example we are using the tap function to keep our method chain going. In addition we are passing the $message parameter into the inner callback function so that we can use it. The above example could actually be simplified further by using the with helper function to return a new instance of Talker:

 1<?php
 2 
 3// ...
 4 
 5function saySomething($message) {
 6    return tap(with(new Talker), function($t) use ($message) {
 7        $t->atBeginning(new Message)->change($message);
 8    })->talk();
 9}
10 
11// ...

The previous example is very contrived but does demonstrate a fairly basic use of the tap helper function. More common use cases might be when passing around Eloquent models with extensive method chaining.

The following example will make use of the Eloquent model factory builder to create a new instance, modify an attribute, save the model and then return the created model instance:

1<?php
2 
3use App\User;
4 
5$user = tap(factory(User::class)->make(), function($user) {
6    $user->setAttribute('name', 'No such a random name')
7         ->save();
8});

After the above example has executed, the attributes of the $user model instance might look similar to the following output:

1array [
2    "name"           => "No such a random name"
3    "email"          => "Batz.Bridget@example.com"
4    "password"       => "$2y$10$aXsXCEx3pkgmNcWpJFkAE.AMHoyk3o8XC6Kth3..."
5    "remember_token" => "nayR2BKwaQ"
6    "updated_at"     => "2016-06-03 22:29:01"
7    "created_at"     => "2016-06-03 22:29:01"
8    "id"             => 7
9  ]

The actual attribute values will differ as they are randomly assigned a value from the model factory. Because of the way we used the tap helper function we were able to modify the name attribute elegantly, save the model and get the exact return value we wanted.

∎