> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Techniques pratiques de Laravel Telescope > Patrons pratiques pour tirer le meilleur parti de Telescope en développement local : détection N+1, suivi par tags, watchers personnalisés, watcher Dump, etc. — un condensé de savoir-faire absent de la documentation officielle. Pour l'installation et la configuration de base, reportez-vous à la [page de guide](/fr/telescope). Cette page présente des patrons pratiques pour le développement local qui ne figurent pas dans la documentation officielle. Telescope est un outil **réservé au développement local**. Pour la supervision de la production, utilisez [Laravel Pulse](/fr/pulse) ou [Laravel Nightwatch](/fr/blog/nightwatch-introduction). *** ## Détecter les problèmes N+1 méthodiquement Voici un flux pratique de debug N+1 avec Telescope. Il ne s'agit pas seulement de « remarquer que le même SELECT se répète » mais de mener toute la démarche, jusqu'à la vérification après correction. ```mermaid theme={null} sequenceDiagram participant Navigateur participant Laravel participant Telescope participant DB Navigateur->>Laravel: GET /posts Laravel->>DB: SELECT * FROM posts (1 requête) loop Pour chaque article Laravel->>DB: SELECT * FROM users WHERE id = ? (N requêtes) end Laravel-->>Navigateur: Réponse Laravel-->>Telescope: Enregistrement des requêtes Note over Telescope: Le même SELECT N fois
Le tag slow est appliqué ``` Ouvrez `/telescope`, onglet Requests, identifiez les requêtes à temps d'exécution élevé. Le détail d'une requête liste toutes les SQL exécutées pendant la requête. Si un même SELECT se répète, c'est un N+1. Ajoutez `with()` et rechargez. Si le nombre de requêtes chute nettement, la correction est bonne. ```php theme={null} // Code qui provoque un N+1 $posts = Post::all(); foreach ($posts as $post) { echo $post->user->name; // Une requête par article } // Solution avec eager loading $posts = Post::with('user')->get(); ``` Toute la démarche se fait dans le navigateur, sans ajouter de `dd()` ni de logs. *** ## Suivi de requêtes précises via les tags Telescope possède une fonctionnalité de **tags**. `Telescope::tag()` ajoute des tags arbitraires à une entrée, ce qui permet de filtrer rapidement le dashboard. Très utile pour suivre les traitements liés à un utilisateur donné ou une commande précise. ```php theme={null} use Laravel\Telescope\IncomingEntry; use Laravel\Telescope\Telescope; // Redéfinir la méthode tags de TelescopeServiceProvider Telescope::tag(function (IncomingEntry $entry) { if ($entry->type === 'request') { return array_filter([ 'status:' . $entry->content['response_status'], auth()->check() ? 'user:' . auth()->id() : null, ]); } return []; }); ``` Sur `/telescope/requests`, taper `user:42` dans la recherche liste immédiatement toutes les requêtes de l'utilisateur 42. ### Tags automatiques sur les modèles Dans la méthode `tags` du `TelescopeServiceProvider`, vous pouvez appliquer l'ID d'un modèle à toutes les entrées. ```php theme={null} // TelescopeServiceProvider Telescope::tag(function (IncomingEntry $entry) { return $entry->tags(); }); ``` En implémentant le contract `HasTags` sur le modèle, ses tags sont ajoutés automatiquement lorsqu'il est enregistré. ```php theme={null} use Laravel\Telescope\Contracts\EntriesRepository; class Order extends Model implements \Laravel\Telescope\Contracts\HasTags { public function telescopeTags(): array { return ['order:' . $this->id]; } } ``` *** ## Utiliser le watcher Dump Utiliser `dump()` peut polluer la réponse HTML et compliquer le debug d'une API. Le watcher Dump de Telescope permet de dévier la sortie de `dump()` vers le dashboard plutôt que la réponse. L'utilisation est simple : ouvrez l'onglet « Dump » de `/telescope` et appelez `dump()`. ```php theme={null} // Contrôleur public function index() { $users = User::with('posts')->get(); dump($users->first()->toArray()); // S'affiche dans l'onglet dump de Telescope return response()->json($users); } ``` La capture n'a lieu que lorsque la page est ouverte, vous ne surveillez que ce dont vous avez besoin. Contrairement à `dd()`, l'application n'est pas interrompue : pratique pour enchaîner des requêtes. *** ## Debug e-mail confortable avec Mailpit Combiner le watcher Mail avec le serveur SMTP local [Mailpit](https://mailpit.axllent.org/) transforme le développement d'e-mails. ```ini theme={null} # .env MAIL_MAILER=smtp MAIL_HOST=127.0.0.1 MAIL_PORT=1025 ``` L'onglet Mail de Telescope prévisualise HTML et texte des e-mails envoyés. Mailpit permet de voir les e-mails reçus dans le navigateur, avec vérification des pièces jointes et du score anti-spam. Pour éviter d'envoyer accidentellement des e-mails en externe, utilisez toujours Mailpit ou Mailhog en local. *** ## Debug d'événements et de listeners L'event-driven est souvent difficile à déboguer. « L'événement est-il déclenché ? », « Quels listeners sont appelés ? » — suivre cela dans les logs est fastidieux. Le watcher Events de Telescope liste les événements dispatchés et leurs listeners. Si un listener n'est pas appelé, ouvrez son entrée dans l'onglet Events. * L'événement est bien dispatché mais aucun listener n'apparaît → listener non enregistré (vérifiez `EventServiceProvider`) * L'événement n'est même pas dispatché → vérifiez l'appel à `event()` ```php theme={null} // À exécuter en local à la place d'un test event(new OrderShipped($order)); // → Vérifier dans /telescope/events que OrderShipped apparaît // → Vérifier que le listener SendShippingConfirmation est appelé ``` *** ## Debug de jobs de queue Déboguer de l'asynchrone à partir des logs seuls est difficile. Le watcher Jobs de Telescope trace du dispatch à l'exécution. Sur un job en échec, cliquez pour voir la stack trace et le message d'exception. Complémentaire à la table `queue:failed`, il accélère l'analyse des échecs. ```php theme={null} // Pour déboguer, le driver sync facilite le suivi (exécution synchrone) // .env QUEUE_CONNECTION=sync ``` Avec le driver sync, le job s'exécute dans la requête et son résultat est inclus dans le watcher Requests. *** ## Debug du client HTTP Pour tracer les échanges avec des API externes, le watcher HTTP Client est très utile. Les requêtes faites via la facade `Http::` et leurs réponses sont enregistrées. ```php theme={null} $response = Http::get('https://api.example.com/users'); // → Visible dans /telescope/client-requests ``` Le contenu de la réponse, le code de statut et le temps d'exécution s'affichent en un coup d'œil. Plus besoin d'écrire `dd($response->json())`. *** ## Conclusion | Technique | Bénéfice | | -------------- | --------------------------------------------------------- | | Workflow N+1 | Trouver et corriger les problèmes de requêtes sans `dd()` | | Tags | Filtrer immédiatement les entrées d'un utilisateur/objet | | Watcher Dump | Voir la sortie de `dump()` sans altérer la réponse API | | Mailpit | Confort de développement e-mail local | | Watcher Events | Visualiser le déclenchement des événements et listeners | | Jobs + sync | Déboguer les asynchrones en synchrone | | Client HTTP | Trace et vérification des appels API externes | Consultez la page guide pour l'installation et la configuration des watchers. Pour la supervision en production, utilisez Nightwatch. ## Related topics - [Cas d'usage pratiques de Laravel Pennant](/fr/blog/laravel-pennant.md) - [Introduction à Laravel Nightwatch](/fr/blog/nightwatch-introduction.md) - [Laravel Telescope](/fr/telescope.md) - [Mode natif - Dictionnaire utilisateur - VOICEVOX for Laravel](/fr/packages/laravel-voicevox/native-user-dict.md) - [Mode client - Dictionnaire utilisateur - VOICEVOX for Laravel](/fr/packages/laravel-voicevox/client-user-dict.md)