User Documentation VS Code - Un IDE gratuit populaire
D'après Wikipedia :
Visual Studio Code, également communément appelé VS Code, est un éditeur de code source créé par Microsoft pour Windows, Linux et macOS. Les fonctionnalités incluent la prise en charge du débogage, la coloration syntaxique, la complétion intelligente du code, les extraits de code, la refactorisation de code, et Git intégré. Les utilisateurs peuvent changer le thème, les raccourcis clavier, les préférences, et installer des extensions qui ajoutent des fonctionnalités supplémentaires.
Installation
La page par défaut du site VS Code propose une liste déroulante pour chaque plateforme prise en charge. Il y a de fortes chances que votre plateforme soit déjà présélectionnée. Il suffit donc de télécharger et d'installer pour être prêt.
Pour commencer
La page Get Started de VS Code propose quelques éléments Démarrer, une liste d'éléments Recent, et une courte liste de Walkthroughs. Si vous découvrez complètement VS Code, leur visionnage est recommandé. Ils ne prennent que quelques minutes.
La documentation de VS Code est disponible depuis le menu Help / Documentation. Les vidéos d'introduction valent vraiment la peine d'être visionnées. Chacune dure de 2 à 6 minutes et offre une excellente introduction aux fonctionnalités de VS Code.
La documentation officielle est l'endroit où se rendre si vous souhaitez rechercher des informations spécifiques.
Extensions VS Code
VS Code peut être utilisé pour tout type de texte, y compris un large éventail de langages de programmation. Il fonctionne avec JavaScript sans ajout d'extensions. Les autres langages sont détectés selon le contexte, donc si vous commencez à créer et enregistrer du code PHP, il est probable qu'il vous soit proposé d'installer un pack de prise en charge PHP.
Cliquer sur l'icône Extensions dans la barre d'activité à gauche pour voir ce qui est installé et ce qui est recommandé. Vous aurez besoin de l'extension PHP Debug !
La disposition de l'écran VS Code
Quelques termes utilisés dans les instructions suivantes :
- Barre d'activité la barre étroite à gauche de l'écran. Sélectionner une icône pour ouvrir ou fermer la barre latérale principale.
- Barre latérale principale lorsqu'elle est ouverte, elle affiche les détails de l'activité sélectionnée.
- Barre d'état en bas de l'écran. Elle indique ce qui se passe.
- Panneau une zone sous les éditeurs de texte pour afficher d'autres informations.
Sélectionner une icône de disposition en haut à droite pour ouvrir ou fermer l'un de ces éléments.
Coder une extension Joomla
Pour créer une extension, l'objectif est de créer un fichier zip que vous pouvez installer dans un site Joomla fonctionnel. Vous avez donc besoin d'un dossier pour contenir votre code. Celui-ci doit se trouver dans votre espace de fichiers personnel sur votre ordinateur portable ou de bureau utilisé pour le développement local. Il ne doit pas se trouver dans l'arborescence de votre site web. Par exemple, vous pourriez utiliser ~/jextensions pour contenir des sous-dossiers pour différentes extensions. J'utilise ~/git car c'est court et facile à épeler, bien que potentiellement source de confusion car chaque sous-dossier utilise un dépôt git distinct.
Exemple de code
Si vous souhaitez un exemple de code sur lequel travailler, une extension est disponible sur GitHub nommée mod_debugme. Comme son nom l'indique, il s'agit d'un module comportant quelques bugs. En plus du code du module, il y a un fichier build.xml pour illustrer une façon d'automatiser la compilation pour les tests et la création d'un fichier zip.
Le module est conçu pour afficher les quelques prochains (3 par défaut) événements (anniversaires) à partir d'une liste stockée dans une table de base de données. On peut imaginer son utilisation dans un bureau ou un site familial, dans l'attente d'un gâteau.
Il est sans doute préférable de commencer en utilisant les commandes git en ligne de commande. Créer d'abord un dossier pour votre code, puis cloner le dépôt distant :
mkdir ~/git
cd ~/git
git clone https://github.com/ceford/j4xdemos-mod-debugme
La réponse ne devrait prendre que quelques secondes :
Cloning into 'j4xdemos-mod-debugme'...
remote: Enumerating objects: 23, done.
remote: Counting objects: 100% (23/23), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 23 (delta 3), reused 23 (delta 3), pack-reused 0
Unpacking objects: 100% (23/23), done.
Vous devriez prendre un moment pour regarder le contenu du dossier :
cd j4xdemos-mod-debugme
ls -al
total 16
drwxr-xr-x 6 ceford staff 192 2 Sep 17:48 .
drwxr-xr-x 3 ceford staff 96 2 Sep 17:48 ..
drwxr-xr-x 12 ceford staff 384 2 Sep 17:48 .git
-rw-r--r-- 1 ceford staff 1402 2 Sep 17:48 README.md
-rw-r--r-- 1 ceford staff 927 2 Sep 17:48 build.xml
drwxr-xr-x 8 ceford staff 256 2 Sep 17:48 mod_debugme
Le Dossier .git contient des informations sur le dépôt. Le fichier README.md est un document markdown qui décrit ce dépôt. Le fichier build.xml est un fichier utilisé pour construire l'extension avec un outil externe, Phing - décrit plus loin. Le Dossier mod_debugme contient le code de l'extension.
Installation dans Joomla
Compressez le Dossier de l'extension pour créer un fichier zip installable :
zip -r mod_debugme.zip mod_debugme
Vous pouvez maintenant installer le fichier zip dans le site Joomla! que vous utilisez pour les tests. Après l'installation, vous devez créer un module 'Site' (frontal) et l'assigner à une position de module. Comme il s'agit d'un module défectueux, vous pouvez l'assigner à une position sur Toutes les pages pendant que vous travaillez dessus ; ou vous pouvez l'assigner à une position sur une seule page ; ou vous pouvez le positionner dans un article qui a son propre lien de menu.
Après l'installation, supprimez le fichier zip.
Activer le mode débogage
Dans la Configuration Générale de Joomla!, réglez Débogage système sur Oui et Rapport d'erreurs sur Maximum.
Lorsque vous ouvrez une page contenant le module défectueux, vous verrez une pile d'appels (stack trace) vous indiquant où une erreur a été déclenchée.
Parfois, l'erreur de code se trouve sur la première ligne de la pile d'appels. Sinon, si l'erreur est déclenchée dans du code de bibliothèque, par exemple en passant des données invalides à une fonction de base de données, l'erreur de code peut se trouver plus bas dans la liste des appels de fonctions.
Ouvrir le dossier de l'extension dans VS Code
Dans VS Code, utilisez le lien de menu Fichier / Ouvrir le Dossier pour localiser et ouvrir le Dossier contenant votre copie locale du code de l'extension mod_debugme. Vous devriez voir quelque chose de similaire à ce qui suit :
Vous pourrez peut-être diagnostiquer le problème simplement en lisant le code. Dans le cas de l'erreur Class "DebugHelper" not found, vous verrez qu'une instruction use a été commentée quelques lignes plus haut. Oublier d'insérer une instruction use est une erreur courante lors du développement initial!
Corrigez ce problème puis compressez et installez à nouveau le module. Cette étape devient un peu fastidieuse lorsque vous avez plusieurs problèmes. C'est là que les outils de build deviennent utiles.
Phing
Phing est un outil en ligne de commande, disponible sur toutes les plateformes, utilisé pour construire des packages logiciels à l'aide d'instructions stockées dans un fichier xml, nommé build.xml par défaut. Pour travailler avec le code d'une extension, il peut être utilisé pour deux choses :
- copier les fichiers modifiés depuis le dossier source de votre extension vers les emplacements corrects dans le dossier de votre site.
- générer un nouveau fichier zip pour les nouvelles installations.
Téléchargez et installez Phing. D'autres outils de build sont disponibles ! Vous pouvez installer Phing dans votre propre dossier bin ou dans un dossier bin système. Vous devez noter le chemin vers votre code Phing. Dans cet exemple, c'est ~/bin/phing-latest.phar. Vous pouvez l'essayer depuis la ligne de commande après vous être déplacé dans le dossier contenant le code de votre extension :
cd ~/git/j4xdemos-mod-debugme
php ~/bin/phing-latest.phar
Réponse :
Buildfile: /Users/ceford/git/j4xdemos-mod-debugme/build.xml
mod_debugme > main:
... Any copied files will be mentioned here
[zip] Building zip: /Users/ceford/zips/mod_debugme.zip
BUILD FINISHED
Total time: 0.0863 seconds
Tâches VS Code
Pour exécuter Phing depuis VS Code, vous devez créer un fichier tasks.json dans le dossier .vscode à la racine du dossier j4xdemos-mod-debugme. Si ce dernier n'existe pas, créez-le d'abord. Créez ensuite le fichier tasks.json et saisissez le code suivant :
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "Build mod_debugme",
"type": "shell",
"command": "php ~/bin/phing-latest.phar",
"windows": {
"command": "php ~/bin/phing-latest.phar"
},
"group": "build",
"presentation": {
"reveal": "always",
"panel": "shared"
}
}
]
}
Les utilisateurs de Windows doivent corriger la commande spécifique à Windows. Vous pouvez maintenant construire l'extension en utilisant le menu Terminal / Run Build Task. Le résultat de la commande doit apparaître dans le panneau Terminal situé sous la zone d'édition.
* Executing task: php ~/bin/phing-latest.phar
Buildfile: /Users/ceford/git/gitdemo/j4xdemos-mod-debugme/build.xml
mod_debugme > main:
[zip] Nothing to do: /Users/ceford/zips/mod_debugme.zip is up to date.
BUILD FINISHED
Total time: 0.1031 seconds
* Terminal will be reused by tasks, press any key to close it.
Il peut arriver que des messages d'erreur incompréhensibles apparaissent. La cause la plus probable est la présence de chemins de dossiers invalides dans le fichier build.xml ou l'absence de création d'un dossier. Encore un autre type de problème à déboguer !
Débogage
Vous devriez pouvoir corriger le premier bug par inspection du code. Les problèmes plus complexes nécessitent de parcourir le code pas à pas avec le débogueur. Cela vous permet d'inspecter les variables pour voir si elles contiennent les valeurs attendues, par exemple lors du passage d'arguments à des fonctions de bibliothèque.
php.ini Paramètres
Pour configurer le débogage avec Xdebug, vous devez ajouter certaines entrées en haut de votre fichier php.ini.
zend_extension="xdebug.so"
xdebug.mode="debug"
xdebug.client_port=9003
xdebug.start_with_request = yes
Après avoir enregistré les modifications, redémarrez votre serveur Apache.
Fenêtre Ajouter un site Web
Votre dossier d'extension ne contient que quelques fichiers, les sources des fichiers installés sur votre site Web. Le débogage à l'exécution implique de définir des points d'arrêt dans vos fichiers du site, vous devez donc avoir accès à ces fichiers. Vous pourriez utiliser le menu Fichier / Ajouter un dossier à l'espace de travail... pour ajouter le dossier du site à votre espace de travail. Cependant, il y a de fortes chances que vous finissiez par modifier les fichiers du site au lieu des fichiers source. Il est donc probablement préférable d'ouvrir une fenêtre VS Code séparée pour le débogage.
- Ouvrir une nouvelle fenêtre : Dans le menu VS Code, sélectionner Fichier / Nouvelle fenêtre puis sélectionner le dossier contenant votre site Joomla.
- Ouvrir un dossier : Dans la fenêtre nouvellement ouverte, sélectionner Fichier / Ouvrir un dossier... dans le menu VS Code. Trouver le dossier de votre site Web et le sélectionner. Vous devriez voir la liste de tous les fichiers de votre site Joomla dans la barre latérale principale.
Configuration de lancement
Pour que le débogage fonctionne réellement dans VS Code, vous avez besoin d'une configuration de lancement. À la racine de votre site Web, créez un dossier nommé .vscode (notez le point en tête) contenant un fichier nommé launch.json avec le contenu suivant :
{
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"hostname": "0.0.0.0",
"port": 9003,
"stopOnEntry": true,
"pathMappings": {
"/Users/ceford/Sites/j421rc2": "${workspaceFolder}"
}
}
]
}
N'oubliez pas de remplacer l'élément pathMappings de cet exemple par les pathMappings réels de votre propre site. L'élément stopOnEntry mettra en pause l'exécution dès la toute première ligne de code PHP exécutée.
Déboguer mod_debugme
Vous êtes maintenant prêt à trouver et corriger les bugs dans le module installé.
- Trouver le code du module : Trouver le premier bug à la ligne 16 de JROOT/modules/mod_debugme/mod_debugme.php.
- Définir un point d'arrêt : Cliquer dans l'espace à gauche du numéro 16. Une pastille rouge pâle apparaît au survol et devient rouge vif après avoir cliqué pour indiquer qu'un point d'arrêt a été défini.
- Démarrer le débogage : Dans le menu VS Code, sélectionner Exécuter / Démarrer le débogage. Dans votre navigateur, recharger votre site. Votre fenêtre VS Code devrait réapparaître avec le code arrêté à la première ligne du fichier index.php du site. En haut de l'écran se trouvent quelques icônes pour contrôler le processus de débogage. Elles devraient être explicites. Sinon, consultez-les dans l'Aide / Documentation de VS Code.
- Continuer : Sélectionner le bouton Continuer - le code s'exécutera jusqu'à votre premier point d'arrêt. Examiner le code pour voir quel est le problème.
- Survol : Si vous survolez une variable à laquelle une valeur a été assignée, une petite infobulle apparaîtra résumant les attributs de cette variable. Il n'y a pas d'infobulle pour les variables qui n'ont pas de valeur assignée.
- Variables : La colonne de gauche contient davantage d'informations sur l'état du code au point d'arrêt. Il y en a trop pour les couvrir ici. Explorez-les selon vos besoins !
- Arrêter le débogage : Il est probablement préférable de sélectionner l'icône Continuer, sinon la page web est livrée vide. Sinon, vous pouvez utiliser le bouton Stop ou le menu Exécuter / Arrêter le débogage.
Corriger un bug
Rappel : Ne corrigez pas le bug dans le code du site web ! Corrigez-le dans le code source !
Corrigez le code source puis utilisez Terminal / Run Build Task....
Redémarrez le débogage.
Astuces
Quelques problèmes pas si évidents :
- Vous corrigez le premier bug mais cela plante toujours sur cette ligne. Regardez dans mod_debugme.xml pour voir où est définie la source des classes à espace de noms. Une fois corrigé dans la source, vous devez réinstaller le fichier zip ou supprimer administrator/cache/autoload_psr4.php. Lorsqu'il est absent, Joomla! reconstruit ce fichier à partir des fichiers manifestes. Mais s'il contient une entrée incorrecte ou manquante, cela n'est pas corrigé tant que l'extension n'est pas réinstallée.
- Parfois vous devez placer un point d'arrêt quelques lignes avant la ligne où l'erreur se produit, surtout si vous souhaitez vérifier les valeurs passées aux appels de fonction.
- La table xxx.yyy\debugme n'existe pas. Ah oui, le code pour créer une table à l'installation et la supprimer à la désinstallation n'a jamais été créé. Vous devrez exécuter une requête sql dans phpMyAdmin en utilisant le contenu du fichier mod\debugme.sql. N'oubliez pas de remplacer #\ dans les noms de tables par le préfixe de votre base de données. Et si cela échoue encore, vérifiez le nom de la table dans le code.
Capture d'écran
Quand tout est corrigé, voici ce que vous pourriez voir :
Cake days?
Références
Depuis la documentation de Joomla! : Visual Studio Code couvre également la configuration d'autres outils, par exemple CodeSniffer et PHPUnit.