tap() est un helper qui permet « d’utiliser une valeur tout en la renvoyant telle quelle ». Il sert à insérer un effet de bord.L’implémentation dans Illuminate\Support\helpers.php est simple.
function tap($value, $callback = null){ if (is_null($callback)) { return new HigherOrderTapProxy($value); } $callback($value); return $value;}
tap() ignore la valeur retournée par le callback. La valeur retournée est toujours la valeur d’origine.
L’usage le plus courant : recevoir une valeur, la traiter, puis la renvoyer telle quelle.
use App\Models\User;$user = tap(User::query()->latest()->firstOrFail(), function (User $model) { $model->update(['last_seen_at' => now()]);});// C'est $user qui est renvoyé, indépendamment de la valeur de retour d'update()
Sans callback, un HigherOrderTapProxy est renvoyé, ce qui permet d’enchaîner directement des appels de méthode.
$updatedUser = tap($user)->update([ 'name' => $name, 'email' => $email,]);// L'instance User d'origine est renvoyée, pas la valeur de retour d'update()
Exécuter uniquement des effets de bord sans changer la valeur retournée
$response = tap($service->handle($request), function ($response) { \Illuminate\Support\Facades\Cache::increment('service_handle_success_total');});
Si vous souhaitez transformer la valeur retournée, utilisez with() ou une affectation de variable classique. Réserver tap() aux effets de bord améliore la lisibilité.
En faisant use Illuminate\Support\Traits\Tappable, vous ajoutez une méthode tap() à votre classe.
trait Tappable{ public function tap($callback = null) { return tap($this, $callback); }}
Elle fournit donc une version méthode d’instance du helper tap().
use Illuminate\Support\Traits\Tappable;class ReportBuilder{ use Tappable;}$builder = new ReportBuilder();$builder = $builder->tap(function (ReportBuilder $instance) { logger()->debug('builder initialized');});
Tappable est pratique pour glisser un effet de bord au milieu d’une API fluide. Associé à Macroable et Conditionable, vous pouvez créer un builder extensible dans l’esprit Laravel.
1
Créer une classe fluide
use Illuminate\Support\Traits\Conditionable;use Illuminate\Support\Traits\Macroable;use Illuminate\Support\Traits\Tappable;class QueryPresetBuilder{ use Macroable; use Conditionable; use Tappable; protected array $filters = []; public function where(string $key, mixed $value): static { $this->filters[$key] = $value; return $this; } public function toArray(): array { return $this->filters; }}
Le cœur de Laravel utilise réellement tap() / Tappable.
Illuminate\Routing\Router combine Macroable et Tappable.
Router::respondWithRoute() utilise tap($route)->bind(...) sans callback : après l’exécution de bind(), la $route d’origine est renvoyée.
Router::prepareResponse() utilise tap(..., fn (...) => event(...)) pour déclencher un événement après la conversion de la réponse.
Illuminate\Testing\Fluent\Concerns\Has implémente une aide aux assertions via la chaîne ->tap(...)->first(...)->etc().
// Extrait de Illuminate\Routing\Router$route = tap($this->routes->getByName($name))->bind($this->currentRequest);return tap(static::toResponse($request, $response), function ($response) use ($request) { $this->events->dispatch(new ResponsePrepared($request, $response));});
Pris isolément, tap() est un petit helper, mais combiné à Macroable et Conditionable, il facilite l’écriture de chaînes de méthodes lisibles très fréquentes dans Laravel.
