Laravel Helper Function: tap

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 method 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 signature of the tap function is:

/** * Call the given Closure with the given value then return the value. * * @param mixed $value * @return mixed */ function tap($value, $callback) {}
The tap helper function was added in Laravel version 5.3 and defined in the src/Illuminate/Support/helpers.php file. This function can easily be integrated into older Laravel code bases as it does not depend on any new fundamental framework components. View the source code here (in new tab).

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:

namespace App; class Message { /** * The actual message. * * @var string */ protected $message = ''; /** * Gets the original message. * * @return string */ public function getOriginal() { return $this->message; } /** * Changes the message. * * @param $message * @return Message */ public function change($message) { $this->message = $message; return $this; } public function __toString() { return strtolower($this->message); } }

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 lowercased variant. The important thing to notice is that the change method returns a reference back to itself.

Stored in the app/Talker.php file:

namespace App; class Talker { /** * The actual parts of the message. * * @var array */ protected $messageParts = []; /** * Adds a message part to the end of the message. * * @param $message * @return Message */ public function atEnd(Message $message) { array_push($this->messageParts, $message); return $message; } /** * Adds a message part to the start of the message. * * @param $message * @return Message */ public function atBeginning(Message $message) { array_unshift($this->messageParts, $message); return $message; } /** * Returns the string representation of the message. * * @return string */ public function talk() { return ucfirst(implode(' ', $this->messageParts)); } }

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:


Originally published at www.laravelfeed.com.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.