SymfonyWorld Online 2020
100% online
30+ talks + workshops
Live + Replay watch talks later

Étape 5: Diagnostiquer les problèmes

5.0 version
Maintained

Diagnostiquer les problèmes

Mettre en place un projet, c’est aussi avoir les bons outils pour déboguer les problèmes.

Installer des dépendances supplémentaires

Rappelez-vous que le projet a été créé avec très peu de dépendances. Pas de moteur de template. Aucun outil de débogage. Pas de système de log. L’idée est que vous pouvez ajouter d’autres dépendances dès que vous en avez besoin. Pourquoi dépendre d’un moteur de template si vous développez une API HTTP ou un outil CLI ?

Comment ajouter d’autres dépendances ? Avec Composer. En plus des paquets « standards » de Composer, nous travaillerons avec deux types de paquets « spéciaux » :

  • Composants Symfony : Paquets qui implémentent les fonctionnalités de base et les abstractions de bas niveau dont la plupart des applications ont besoin (routage, console, client HTTP, mailer, cache, etc.) ;
  • Bundles Symfony : Paquets qui ajoutent des fonctionnalités de haut niveau ou fournissent des intégrations avec des bibliothèques tierces (les bundles sont principalement créés par la communauté).

Pour commencer, ajoutons le Symfony Profiler. Il vous fait gagner un temps fou lorsque vous avez besoin de trouver l’origine d’un problème :

1
$ symfony composer req profiler --dev

profiler est un alias pour le paquet symfony/profiler-pack.

Les alias ne sont pas une fonctionnalité interne à Composer, mais un concept fourni par Symfony pour vous faciliter la vie. Les alias sont des raccourcis pour les paquets populaires de Composer. Vous voulez un ORM pour votre application ? Demandez orm. Vous voulez développer une API ? Demandez api. Ces alias font référence à un ou plusieurs paquets normaux de Composer. Ce sont des choix arbitraires faits par l’équipe principale de Symfony.

Un autre détail intéressant est que vous pouvez toujours omettre le symfony du nom des paquets. Demandez cache au lieu de symfony/cache.

Astuce

Vous souvenez-vous que nous avons mentionné un plugin Composer nommé symfony/flex ? Les alias sont l’une de ses fonctionnalités.

Comprendre les environnements Symfony

Avez-vous remarqué l’option --dev sur la commande composer req ? Comme le Symfony Profiler n’est utile que pendant le développement, nous voulons éviter qu’il soit installé en production.

Symfony intègre une notion d”environnement. Par défaut, il y en a trois, mais vous pouvez en ajouter autant que vous le souhaitez : dev, prod et test. Tous les environnements partagent le même code, mais ils représentent des configurations différentes.

Par exemple, tous les outils de débogage sont activés en environnement de dev. Dans celui de prod, l’application est optimisée pour la performance.

Basculer d’un environnement à l’autre peut se faire en changeant la variable d’environnement APP_ENV.

Lorsque vous avez déployé vers SymfonyCloud, l’environnement (stocké dans APP_ENV) a été automatiquement modifié en prod.

Gérer la configuration des environnements

APP_ENV peut être défini en utilisant des variables d’environnement « réelles » depuis votre terminal :

1
$ export APP_ENV=dev

L’utilisation de variables d’environnement réelles est la meilleure façon de définir des valeurs comme APP_ENV en production. Mais sur les machines de développement, avoir à définir beaucoup de variables d’environnement peut s’avérer fastidieux. Définissez-les plutôt dans un fichier .env.

Un fichier sensible .env a été généré automatiquement pour vous lorsque le projet a été créé :

.env
1
2
3
4
5
6
###> symfony/framework-bundle ###
APP_ENV=dev
APP_SECRET=c2927f273163f7225a358e3a1bbbed8a
#TRUSTED_PROXIES=127.0.0.1,127.0.0.2
#TRUSTED_HOSTS='^localhost|example\.com$'
###< symfony/framework-bundle ###

Astuce

N’importe quel paquet peut ajouter plus de variables d’environnement à ce fichier grâce à leur recette utilisée par Symfony Flex.

Le fichier .env est commité sur le dépôt Git et liste les valeurs par défaut de la production. Vous pouvez surcharger ces valeurs en créant un fichier .env.local. Ce fichier ne doit pas être commité : c’est pourquoi le fichier .gitignore l’ignore déjà.

Ne stockez jamais des données secrètes ou sensibles dans ces fichiers. Nous verrons comment gérer ces données sensibles dans une autre étape.

Enregistrer tout dans les logs

Par défaut, les capacités de logging et de débogage sont limitées sur les nouveaux projets. Ajoutons d’autres outils pour nous aider à comprendre les problèmes en développement, mais aussi en production :

1
$ symfony composer req logger

Pour les outils de débogage, ne les installons que pour le développement :

1
$ symfony composer req debug --dev

Découvrir les outils de débogage de Symfony

Si vous rafraîchissez la page d’accueil, vous devriez maintenant voir une barre d’outils en bas de l’écran :

La première chose que vous remarquerez, c’est le 404 en rouge. Rappelez-vous que ce n’est qu’une page de remplissage, car nous n’avons toujours pas défini de page d’accueil. Même si la page par défaut qui vous accueille est belle, c’est quand même une page d’erreur. Le code d’état HTTP correct est donc 404, pas 200. Grâce à la web debug toolbar, vous avez l’information tout de suite.

Si vous cliquez sur le petit point d’exclamation, vous obtenez le « vrai » message d’exception dans les logs du Symfony Profiler. Si vous voulez voir la stack trace, cliquez sur le lien « Exception » dans le menu de gauche.

Chaque fois qu’il y a un problème avec votre code, vous verrez une page d’exception comme celle-ci qui vous donnera tout ce dont vous aurez besoin pour comprendre le problème et d’où il vient :

Prenez le temps d’explorer les informations à l’intérieur du profileur Symfony en cliquant partout.

Les logs sont également très utiles dans les sessions de débogage. Symfony a une commande pratique pour consulter tous les logs (du serveur web, de PHP et de votre application) :

1
$ symfony server:log

Réalisons une petite expérience. Ouvrez public/index.php et cassez le code PHP (ajoutez foobar au milieu du code par exemple). Rafraîchissez la page dans le navigateur et observez le contenu des logs :

1
2
Dec 21 10:04:59 |DEBUG| PHP    PHP Parse error:  syntax error, unexpected 'use' (T_USE) in public/index.php on line 5 path="/usr/bin/php7.42" php="7.42.0"
Dec 21 10:04:59 |ERROR| SERVER GET  (500) / ip="127.0.0.1"

Le résultat est joliment coloré pour attirer votre attention sur les erreurs.

Une autre grande aide au débogage est la fonction Symfony dump(). Elle est toujours disponible et vous permet d’afficher des variables complexes dans un format agréable et interactif.

Modifiez temporairement public/index.php pour afficher l’objet Request :

patch_file
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
--- a/public/index.php
+++ b/public/index.php
@@ -23,5 +23,8 @@ if ($trustedHosts = $_SERVER['TRUSTED_HOSTS'] ?? $_ENV['TRUSTED_HOSTS'] ?? false
 $kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
 $request = Request::createFromGlobals();
 $response = $kernel->handle($request);
+
+dump($request);
+
 $response->send();
 $kernel->terminate($request, $response);

Lors du rafraîchissement de la page, remarquez la nouvelle icône « cible » dans la barre d’outils ; elle vous permet d’inspecter le dump. Cliquez dessus pour accéder à une page dédiée où la navigation est simplifiée :

Annulez les modifications avant de commiter les autres modifications effectuées dans cette étape :

1
$ git checkout public/index.php

Configurer votre IDE

En environnement de développement, lorsqu’une exception est levée, Symfony affiche une page avec le message de l’exception et sa stack trace. Lors de l’affichage d’un chemin de fichier, un lien, qui ouvre le fichier à la bonne ligne dans votre IDE favori, est ajouté. Pour bénéficier de cette fonctionnalité, vous devez configurer votre IDE. Symfony supporte de nombreux IDE par défaut ; j’utilise Visual Studio Code pour ce projet :

patch_file
1
2
3
4
5
6
7
8
--- a/config/packages/framework.yaml
+++ b/config/packages/framework.yaml
@@ -14,3 +14,5 @@ framework:
     #fragments: true
     php_errors:
         log: true
+
+    ide: vscode

Les fichiers liés ne sont pas limités à des exceptions. Par exemple, le contrôleur dans la web debug toolbar devient cliquable après avoir configuré l’IDE.

Déboguer en production

Le débogage des serveurs de production est toujours plus délicat. Vous n’avez pas accès au Symfony Profiler par exemple. Les logs sont moins détaillés. Mais il est possible de consulter les logs :

1
$ symfony logs

Vous pouvez même vous connecter en SSH sur le conteneur web :

1
$ symfony ssh

Ne vous inquiétez pas, vous ne pouvez rien casser facilement. Une grande partie du système de fichiers est en lecture seule. Vous ne serez pas en mesure de faire un correctif urgent en production, mais vous apprendrez une manière bien plus adaptée de le faire plus loin dans le livre.


This work, including the code samples, is licensed under a Creative Commons BY-NC-SA 4.0 license.