February 24, 2025 - Understanding Laravel's TAP Helper

Laravel

Laravel's tap helper is a powerful utility that allows you to work with a value and return it without breaking the chain of operations. Let's explore how it works and how to use it effectively.

The TAP Function

At its core, the tap helper is a simple yet powerful function:

if (! function_exists('tap')) {
    /**
     * Call the given Closure with the given value then return the value.
     *
     * @template TValue
     *
     * @param  TValue  $value
     * @param  (callable(TValue): mixed)|null  $callback
     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : TValue)
     */
    function tap($value, $callback = null)
    {
        if (is_null($callback)) {
            return new HigherOrderTapProxy($value);
        }

        $callback($value);

        return $value;
    }
}

The function does two key things:

If no callback is provided, it returns a HigherOrderTapProxy instance
If a callback is provided, it executes the callback with the value and returns the original value

Basic Usage

The tap helper allows you to "tap" into a chain of methods to perform operations on an object while still returning the original value.

$user = tap(User::first(), function($user) {
    $user->update(['last_login' => now()]);
});

Why Use TAP?

Without tap, you might write:

$user = User::first();
$user->update(['last_login' => now()]);
return $user;

With tap, it's more concise:

return tap(User::first(), function($user) {
    $user->update(['last_login' => now()]);
});

Real-World Examples

Example 1: File Operations

use Illuminate\Support\Facades\Storage;

$path = tap(Storage::put('path/to/file.txt', 'contents'), function() {
    Cache::forget('file-cache');
    Log::info('File was updated');
});

$post = tap(Post::create([
    'title' => 'My Post',
    'content' => 'Post content'
]), function($post) {
    $post->tags()->attach([1, 2, 3]);
    $post->user->notify(new PostCreated($post));
});

Example 3: Collection Manipulation

$processedUsers = tap(User::all(), function($users) {
    $users->each->notify(new WelcomeNotification);
    Cache::put('users', $users);
});

Using TAP with Arrow Functions

PHP 7.4+ allows for more concise syntax:

$user = tap(User::first(), fn($user) => $user->update(['last_login' => now()]));

The tap() Method on Collections

Laravel collections include a tap method:

collect([1, 2, 3])
    ->tap(function($collection) {
        Log::info('Count: ' . $collection->count());
    })
    ->filter(fn($value) => $value > 1)
    ->tap(function($collection) {
        Log::info('Filtered Count: ' . $collection->count());
    });

// Count: 3  
// Filtered Count: 2

Testing with TAP

TAP is particularly useful in tests:

public function test_user_creation()
{
    $user = tap(User::factory()->create(), function($user) {
        $this->assertDatabaseHas('users', [
            'id' => $user->id,
            'email' => $user->email
        ]);
    });

    $this->actingAs($user);
}

Common Use Cases

Logging Operations:

$response = tap($service->process(), function($result) {
    Log::info('Process completed', ['result' => $result]);
});

Cache Operations:

$posts = tap(Post::all(), function($posts) {
    Cache::put('all_posts', $posts, now()->addDay());
});

File Handling:

$file = tap(new UploadedFile(), function($file) {
    Storage::disk('public')->put('path/to/file', $file);
    event(new FileUploaded($file));
});

Best Practices

Use tap when you need to perform side effects without breaking the chain
Consider tap for cleaner testing code
Combine with arrow functions for more concise syntax
Use collection's tap method when working with collections

Conclusion

The tap helper is a powerful tool for writing cleaner, more maintainable code in Laravel. It's particularly useful for performing side effects while maintaining a fluent interface in your code.

For more information, check out the Laravel documentation.