User Documentation VS Code - Un IDE gratuito molto diffuso
Da Wikipedia:
Visual Studio Code, comunemente noto anche come VS Code, è un editor di codice sorgente creato da Microsoft per Windows, Linux e macOS. Le funzionalità includono il supporto per il debug, l'evidenziazione della sintassi, il completamento intelligente del codice, gli snippet, il refactoring del codice e Git integrato. Gli utenti possono cambiare il tema, le scorciatoie da tastiera, le preferenze e installare estensioni che aggiungono ulteriori funzionalità.
Installazione
La pagina predefinita del sito VS Code ha un menu a tendina per ogni piattaforma supportata. È probabile che la tua piattaforma sia già pre-selezionata. Scarica e installa quindi sei pronto per iniziare.
Per iniziare
La pagina Get Started di VS Code presenta alcuni elementi Start, una lista di elementi Recent e una breve lista di Walkthroughs. Se non hai mai usato VS Code prima d'ora, se ne consiglia la visione. Richiedono solo pochi minuti.
La documentazione di VS Code è disponibile dal menu Help / Documentation. I video introduttivi meritano di essere visti. Ognuno dura dai 2 ai 6 minuti e offre un'ottima introduzione alle funzionalità di VS Code.
La documentazione ufficiale è il posto giusto da consultare se vuoi cercare informazioni specifiche.
Estensioni di VS Code
VS Code può essere usato per qualsiasi tipo di testo, compresa un'ampia gamma di linguaggi di programmazione. Funziona con JavaScript senza bisogno di aggiungere estensioni. Altri linguaggi vengono rilevati in base al contesto, quindi se inizi a creare e salvare codice PHP ti verrà probabilmente proposto di installare un pacchetto di supporto PHP.
Clicca sull'icona Estensioni nella Activity Bar a sinistra per vedere cosa hai installato e cosa viene consigliato. Avrai bisogno dell'estensione PHP Debug!
Il layout dello schermo di VS Code
Alcuni termini usati nelle istruzioni seguenti:
- Activity Bar la barra stretta sulla sinistra dello schermo. Clicca su un'icona qualsiasi per aprire o chiudere la Primary Sidebar.
- Primary Side Bar quando aperta mostra i dettagli dell'attività selezionata.
- Status Bar in fondo allo schermo. Mostra cosa sta succedendo.
- Panel un'area sotto gli editor di testo per mostrare altre informazioni.
Clicca su un'icona di layout in alto a destra per aprire o chiudere uno di questi elementi.
Scrivere un'estensione Joomla
Per creare un'estensione il tuo obiettivo è creare un file zip che possa essere installato in un sito Joomla funzionante. Quindi ti serve una cartella che contenga il tuo codice. Questa dovrebbe trovarsi all'interno del tuo spazio file personale sul portatile o computer desktop usato per lo sviluppo locale. Non dovrebbe trovarsi nell'albero del tuo sito web. Ad esempio potresti usare ~/jextensions per contenere sottocartelle per diverse estensioni. Io uso ~/git perché è breve e facile da digitare, anche se potenzialmente fuorviante poiché ogni sottocartella usa un repository git separato.
Codice di esempio
Se vuoi del codice di esempio su cui lavorare, è disponibile su GitHub un'estensione chiamata mod_debugme. Come suggerisce il nome, si tratta di un modulo con alcuni bug. Oltre al codice del modulo è presente un file build.xml che illustra un modo per automatizzare la compilazione per i test e la creazione di un file zip.
Il modulo è progettato per mostrare i prossimi (3 per impostazione predefinita) eventi (compleanni) da una lista memorizzata in una tabella del database. Potresti immaginarne l'uso in un ufficio o in un sito di famiglia, in attesa della torta.
Potrebbe essere meglio iniziare usando i comandi git dalla riga di comando. Per prima cosa crea una cartella per il tuo codice e poi clona il repository remoto:
mkdir ~/git
cd ~/git
git clone https://github.com/ceford/j4xdemos-mod-debugme
La risposta dovrebbe richiedere solo pochi secondi:
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.
Dovresti dedicare un momento a guardare il contenuto della cartella:
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
La cartella .git contiene informazioni sul repository. Il file README.md è un documento in formato markdown che descrive questo repository. Il file build.xml è un file usato per compilare l'estensione con uno strumento esterno, Phing - descritto più avanti. La cartella mod_debugme contiene il codice dell'estensione.
Installare in Joomla
Comprimi la cartella dell'estensione per creare un file zip installabile:
zip -r mod_debugme.zip mod_debugme
Ora puoi installare il file zip nel sito Joomla che usi per i test. Dopo l'installazione devi creare un modulo sito e assegnarlo a una posizione modulo. Trattandosi di un modulo difettoso potresti assegnarlo a una posizione su Tutte le pagine mentre ci lavori; oppure potresti assegnarlo a una posizione su una singola pagina; oppure potresti posizionarlo in un articolo che ha una propria voce di menu.
Dopo l'installazione, elimina il file zip.
Attivare la modalità debug
Nella Configurazione globale di Joomla, imposta Sistema debug su Sì e Livello di segnalazione errori su Massimo.
Quando apri una pagina contenente il modulo difettoso vedrai uno stack trace che indica dove è stato generato un errore.
A volte l'errore di codifica si trova sulla prima riga dello stack trace. In caso contrario, se l'errore viene generato nel codice di libreria, ad esempio passando dati non validi a una funzione del database, l'errore di codifica potrebbe trovarsi più in basso nell'elenco delle chiamate di funzione.
Aprire la cartella dell'estensione in VS Code
In VS Code, usa la voce di menu File / Apri cartella per individuare e aprire la cartella contenente la tua copia locale del codice dell'estensione mod_debugme. Dovresti vedere qualcosa di simile a quanto segue:
Potresti essere in grado di diagnosticare il problema semplicemente leggendo il codice. Nel caso dell'errore Class "DebugHelper" not found vedrai che un'istruzione use è stata commentata poche righe prima. Dimenticare di inserire un'istruzione use è un errore comune durante lo sviluppo iniziale!
Risolvi quel problema e poi comprimi e installa di nuovo il modulo. Questo passo diventa un po' noioso quando hai diversi problemi. Ed è qui che gli strumenti di build tornano utili.
Phing
Phing è uno strumento a riga di comando, disponibile per tutte le piattaforme, utilizzato per creare pacchetti software usando istruzioni memorizzate in un file xml, chiamato build.xml per impostazione predefinita. Per lavorare con il codice delle estensioni può essere usato per fare due cose:
- copiare i file modificati dalla cartella sorgente della tua estensione ai posti corretti nella cartella del tuo sito web.
- generare un nuovo file zip per le nuove installazioni.
Scarica e installa Phing. Sono disponibili altri strumenti di build! Puoi installare Phing nella tua cartella bin personale o in una cartella bin di sistema. Devi annotare il percorso del tuo codice Phing. In questo esempio è ~/bin/phing-latest.phar. Puoi provarlo dalla riga di comando dopo esserti spostato nella cartella contenente il codice della tua estensione:
cd ~/git/j4xdemos-mod-debugme
php ~/bin/phing-latest.phar
Risposta:
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
Attività di VS Code
Per eseguire Phing da dentro VS Code devi creare un file tasks.json nella cartella .vscode nella radice della cartella j4xdemos-mod-debugme. Se quest'ultima non esiste, creala prima. Poi crea il file tasks.json e inserisci il seguente codice:
{
// 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"
}
}
]
}
Gli utenti Windows devono correggere il comando specifico per Windows. Ora puoi compilare l'estensione usando il menu Terminal / Run Build Task. Il risultato del comando dovrebbe apparire nel Terminal Panel sotto l'area di modifica.
* 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.
Potrebbero comparire messaggi di errore incomprensibili. La causa più probabile è avere percorsi non validi alle cartelle nel file build.xml oppure una cartella non è stata creata. Solo un altro tipo di problema da debuggare!
Debug
Dovresti essere in grado di correggere il primo bug ispezionando il codice. Problemi più complicati richiedono di scorrere passo passo il codice con il debugger. Questo ti permette di ispezionare le variabili per vedere se contengono i valori che ti aspetti, ad esempio quando passi argomenti a funzioni di libreria.
php.ini
Per configurare il debug con Xdebug devi aggiungere alcune voci all'inizio del tuo file php.ini.
zend_extension="xdebug.so"
xdebug.mode="debug"
xdebug.client_port=9003
xdebug.start_with_request = yes
Dopo aver salvato le modifiche, riavvia il tuo server Apache.
Finestra Aggiungi sito web
La cartella della tua estensione contiene solo pochi file, i sorgenti dei file installati nel tuo sito web. Il debug in esecuzione comporta l'impostazione di punti di interruzione nei file del tuo sito, quindi hai bisogno di accedere a quei file. Potresti usare il menu File / Aggiungi cartella allo spazio di lavoro... per aggiungere la cartella del sito al tuo Workspace. Tuttavia, c'è una buona probabilità che tu finisca per apportare modifiche ai file del sito invece che ai file sorgente. Quindi è probabilmente meglio aprire una finestra separata di VS Code per il debug.
- Apri nuova finestra: Dal menu di VS Code, clicca File / Nuova finestra e seleziona la cartella contenente il tuo sito Joomla.
- Apri cartella: Nella finestra appena aperta, clicca File / Apri cartella... dal menu di VS Code. Trova la cartella del tuo sito web e selezionala. Dovresti vedere una lista di tutti i file del tuo sito Joomla nella Primary Side Bar.
Configurazione di avvio
Perché il debug funzioni effettivamente in VS Code hai bisogno di una configurazione di avvio. Nella radice del tuo sito web crea una cartella chiamata .vscode (nota il punto iniziale) contenente un file chiamato launch.json con il seguente contenuto:
{
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"hostname": "0.0.0.0",
"port": 9003,
"stopOnEntry": true,
"pathMappings": {
"/Users/ceford/Sites/j421rc2": "${workspaceFolder}"
}
}
]
}
Ricorda di sostituire la voce pathMappings in questo esempio con il pathMappings effettivo del tuo sito. La voce stopOnEntry metterà in pausa l'esecuzione alla primissima riga di codice PHP eseguito.
Debug di mod_debugme
Ora sei pronto per trovare e correggere i bug nel modulo installato.
- Trova il codice del modulo: Trova il primo bug alla riga 16 di JROOT/modules/mod_debugme/mod_debugme.php.
- Imposta punto di interruzione: Clicca nello spazio a sinistra del numero 16. Apparirà una macchia rosso pallido mentre ci passi sopra e diventerà rosso pieno dopo il clic per indicare che è stato impostato un punto di interruzione.
- Avvia debug: Dal menu di VS Code clicca Run / Start Debugging. Nel tuo browser ricarica il tuo sito. La tua finestra di VS Code dovrebbe riapparire con il codice fermato alla prima riga del file index.php del sito. In cima allo schermo ci sono alcune icone per controllare il processo di debug. Dovrebbero essere autoesplicative. In caso contrario, cercale nella Guida/Documentazione di VS Code.
- Continua: Clicca il pulsante continua - il codice andrà avanti fino al tuo primo punto di interruzione. Esamina il codice per vedere qual è il problema.
- Passa il mouse sopra: Se passi il mouse sopra una variabile a cui è stato assegnato un valore apparirà un piccolo Tooltip che riassume gli attributi di quella variabile. Non c'è Tooltip per le variabili a cui non è stato assegnato un valore.
- Variabili: La colonna di sinistra contiene ulteriori informazioni sullo stato del codice al punto di interruzione. Sono troppe per essere trattate qui. Esplorale secondo necessità!
- Interrompi debug: Probabilmente è meglio selezionare l'icona Continua, altrimenti la pagina web viene visualizzata vuota. In alternativa puoi usare il pulsante Stop o il menu Run / Stop Debugging.
Correggi un bug
Ricorda: Non correggere il bug nel codice del sito web! Correggilo nel codice sorgente!
Correggi il codice sorgente e poi usa Terminal / Run Build Task....
Riavvia il debug.
Suggerimenti
Alcuni problemi non così ovvi:
- Correggi il primo bug ma continua a bloccarsi su quella riga. Guarda in mod_debugme.xml per vedere dove è definito il src delle classi con namespace. Quando corretto nel sorgente devi reinstallare il file zip oppure eliminare administrator/cache/autoload_psr4.php. Quando assente, Joomla ricostruisce quel file dai file manifest. Ma se contiene una voce errata o mancante non viene corretto finché l'estensione non viene reinstallata.
- A volte devi impostare un punto di interruzione alcune righe prima di quella in cui si verifica l'errore, specialmente se vuoi controllare i valori passati alle chiamate di funzione.
- La tabella xxx.yyy\debugme non esiste. Ah sì, il codice per creare una tabella all'installazione e rimuoverla alla disinstallazione non è mai stato creato. Dovrai eseguire una query sql in phpMyAdmin usando il contenuto del file mod\debugme.sql. Ricorda di cambiare #\ nei nomi delle tabelle con il prefisso del tuo database. E se ancora non funziona controlla il nome della tabella nel codice.
Schermata
Quando tutto è corretto ecco cosa potresti vedere:
Giorni di torta?
Riferimenti
Dalla documentazione di Joomla!: Visual Studio Code copre anche la configurazione di altri strumenti, ad esempio CodeSniffer e PHPUnit.