User Documentation VS Code — um IDE gratuito popular
Da Wikipédia:
O Visual Studio Code, também vulgarmente referido como VS Code, é um editor de código-fonte criado pela Microsoft para Windows, Linux e macOS. As funcionalidades incluem suporte para depuração, realce de sintaxe, conclusão inteligente de código, trechos de código, refatoração de código e Git integrado. Os utilizadores podem alterar o tema, os atalhos de teclado, as preferências e instalar extensões que adicionam funcionalidades extra.
Instalação
A página predefinida do sítio do VS Code tem uma lista pendente para cada plataforma suportada. É provável que a sua plataforma já esteja pré-selecionada. Basta descarregar e instalar para estar pronto a começar.
Introdução
A página Get Started do VS Code tem alguns itens em Start, uma lista de itens Recent e uma pequena lista de Walkthroughs. Se for completamente novo no VS Code, recomenda-se a visualização destes. Demoram apenas alguns minutos.
A documentação do VS Code está disponível no menu Help / Documentation. Os Vídeos Introdutórios valem bem a pena ver. Cada um demora entre 2 a 6 minutos e dá uma excelente introdução às funcionalidades do VS Code.
A documentação oficial é o sítio ideal para consultar informações específicas.
Extensões do VS Code
O VS Code pode ser usado para qualquer tipo de texto, incluindo uma vasta gama de linguagens de programação. Funciona com JavaScript sem necessidade de adicionar extensões. Outras linguagens são detetadas pelo contexto, pelo que, se começar a criar e a guardar código PHP, é provável que lhe seja sugerido instalar um pacote de suporte a PHP.
Clique no ícone Extensions na Activity Bar à esquerda para ver o que tem instalado e o que é recomendado. Vai precisar da extensão PHP Debug!
A disposição do ecrã do VS Code
Alguns termos usados nas instruções seguintes:
- Activity Bar a barra estreita à esquerda do ecrã. Selecione qualquer ícone para abrir ou fechar a Primary Sidebar.
- Primary Side Bar quando aberta, mostra detalhes da atividade selecionada.
- Status Bar na parte inferior do ecrã. Mostra o que está a acontecer.
- Panel uma área por baixo dos editores de texto para exibir outras informações.
Selecione um ícone de disposição no canto superior direito para abrir ou fechar qualquer um destes elementos.
Codificar uma extensão Joomla
Para criar uma extensão, o seu objetivo é criar um ficheiro zip que possa instalar num sítio Joomla em funcionamento. Assim, precisa de uma pasta para conter o seu código. Esta deve estar dentro do seu espaço de ficheiros pessoal no portátil ou computador de secretária usado para desenvolvimento local. Não deve estar na árvore do seu sítio web. Por exemplo, pode usar ~/jextensions para conter subpastas para diferentes extensões. Eu uso ~/git porque é curto e fácil de escrever, embora potencialmente confuso, já que cada subpasta usa um repositório git separado.
Código de exemplo
Se quiser algum código de exemplo para trabalhar, há uma extensão disponível no GitHub chamada mod_debugme. Como o nome indica, é um módulo com alguns erros. Além do código do módulo, há um ficheiro build.xml para ilustrar uma forma de automatizar a compilação para testes e a criação de um ficheiro zip.
O módulo foi concebido para mostrar os próximos (3 por predefinição) eventos (aniversários) de uma lista armazenada numa tabela da base de dados. Pode imaginar isto a ser usado num escritório ou num sítio familiar com a expectativa de bolo.
Talvez seja melhor começar por usar comandos git a partir da linha de comandos. Primeiro, crie uma pasta para o seu código e depois clone o repositório remoto:
mkdir ~/git
cd ~/git
git clone https://github.com/ceford/j4xdemos-mod-debugme
A resposta deve demorar apenas alguns segundos:
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.
Deve dedicar um momento a observar o conteúdo da pasta:
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
A pasta .git contém informações sobre o repositório. O ficheiro README.md é um documento markdown que descreve este repositório. O ficheiro build.xml é um ficheiro usado para compilar a extensão com uma ferramenta externa, o Phing - descrito mais adiante. A pasta mod_debugme contém o código da extensão.
Instalar no Joomla
Comprima a pasta da extensão para criar um ficheiro zip instalável:
zip -r mod_debugme.zip mod_debugme
Pode agora instalar o ficheiro zip no sítio Joomla que utiliza para testes. Após a instalação, precisa de criar um módulo de sítio e atribuí-lo a uma Função do módulo. Como se trata de um módulo com erros, pode atribuí-lo a uma Função em Todas as páginas enquanto trabalha nele; ou pode atribuí-lo a uma Função numa única página; ou pode posicioná-lo num artigo que tenha o seu próprio Item de menu.
Após a instalação, elimine o ficheiro zip.
Ativar o Modo de depuração
Na Configuração global do Joomla, defina Depurar sistema para Sim e Relatório de erros para Máximo.
Ao abrir uma página que contenha o módulo com erro, verá um stack trace que indica onde o erro foi despoletado.
Por vezes, o erro de programação encontra-se na primeira linha do stack trace. Caso contrário, se o erro for despoletado em código de biblioteca, por exemplo ao passar dados inválidos a uma função de base de dados, o erro de programação pode estar mais abaixo na lista de chamadas de função.
Abrir a pasta da extensão no VS Code
No VS Code, use o item de menu Ficheiro / Abrir pasta para localizar e abrir a pasta que contém a sua cópia local do código da extensão mod_debugme. Deverá ver algo semelhante ao seguinte:
Pode ser possível diagnosticar o problema apenas lendo o código. No caso do erro Class "DebugHelper" not found verá que uma instrução use foi comentada algumas linhas antes. Esquecer de inserir uma instrução use é um erro comum durante o desenvolvimento inicial!
Corrija esse problema e depois comprima e instale o módulo novamente. Este passo torna-se um pouco cansativo quando há múltiplos problemas. É aqui que as ferramentas de compilação se tornam úteis.
Phing
O Phing é uma ferramenta de linha de comandos, disponível para todas as plataformas, utilizada para compilar pacotes de software usando instruções armazenadas num ficheiro xml, denominado build.xml por predefinição. Para trabalhar com código de extensões pode ser usado para fazer duas coisas:
- copiar ficheiros alterados da pasta de código-fonte da extensão para os locais corretos na pasta do seu site.
- gerar um novo ficheiro zip para novas instalações.
Descarregue e instale o Phing. Estão disponíveis outras ferramentas de compilação! Pode instalar o Phing na sua própria pasta bin ou numa pasta bin do sistema. Precisa de anotar o caminho para o código do Phing. Neste exemplo é ~/bin/phing-latest.phar. Pode experimentá-lo a partir da linha de comandos depois de mudar para a pasta que contém o código da sua extensão:
cd ~/git/j4xdemos-mod-debugme
php ~/bin/phing-latest.phar
Resposta:
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
Tarefas do VS Code
Para executar o Phing a partir do VS Code precisa de criar um ficheiro tasks.json na pasta .vscode na raiz da pasta j4xdemos-mod-debugme. Se esta última não existir, primeiro crie-a. Depois crie o ficheiro tasks.json e insira o seguinte código:
{
// 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"
}
}
]
}
Os utilizadores de Windows precisam de corrigir o comando específico do Windows. Pode agora compilar a extensão utilizando o menu Terminal / Run Build Task. O resultado do comando deverá aparecer no Terminal Panel abaixo da área de edição.
* 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.
Pode haver mensagens de erro incompreensíveis. A causa mais provável é ter caminhos inválidos para pastas no ficheiro build.xml ou uma pasta que não foi criada. Mais um tipo de problema para depurar!
Depuração
Deverá conseguir corrigir o primeiro erro por inspeção do código. Problemas mais complicados requerem percorrer o código passo a passo com o depurador. Isso permite-lhe inspecionar variáveis para ver se contêm os valores esperados, por exemplo ao passar argumentos para funções de bibliotecas.
php.ini — configurações
Para configurar a depuração com o Xdebug precisa de adicionar algumas entradas no início do seu ficheiro php.ini.
zend_extension="xdebug.so"
xdebug.mode="debug"
xdebug.client_port=9003
xdebug.start_with_request = yes
Após guardar quaisquer alterações, reinicie o seu servidor Apache.
Janela adicionar sítio web
A sua pasta de extensão contém apenas alguns ficheiros, as fontes dos ficheiros instalados no seu sítio web. A depuração em tempo de execução envolve a definição de pontos de interrupção nos ficheiros do seu sítio, pelo que precisa de aceder a esses ficheiros. Poderia utilizar o menu File / Add Folder to Workspace... para adicionar a pasta do sítio ao seu Workspace. No entanto, há uma grande probabilidade de acabar por fazer alterações aos ficheiros do sítio em vez dos ficheiros fonte. Por isso, é provavelmente melhor abrir uma janela separada do VS Code para depuração.
- Abrir nova janela: No menu do VS Code, selecione File / New Window e selecione a pasta que contém o seu sítio web Joomla.
- Abrir pasta: Na janela recém-aberta, selecione File / Open Folder... no menu do VS Code. Encontre a pasta do seu sítio web e selecione-a. Deverá ver uma lista de todos os ficheiros do seu sítio web Joomla na Primary Side Bar.
Configuração de arranque
Para que a depuração funcione realmente no VS Code, precisa de uma configuração de arranque. Na raiz do seu sítio web, crie uma pasta denominada .vscode (note o ponto inicial) contendo um ficheiro denominado launch.json com o seguinte conteúdo:
{
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"hostname": "0.0.0.0",
"port": 9003,
"stopOnEntry": true,
"pathMappings": {
"/Users/ceford/Sites/j421rc2": "${workspaceFolder}"
}
}
]
}
Lembre-se de substituir o item pathMappings deste exemplo pelo pathMappings real do seu próprio sítio. O item stopOnEntry fará uma pausa na execução logo na primeira linha de código PHP executado.
Depurar mod_debugme
Agora está pronto para encontrar e corrigir os erros no módulo instalado.
- Encontrar o código do módulo: Encontre o primeiro erro na linha 16 de JROOT/modules/mod_debugme/mod_debugme.php.
- Definir ponto de interrupção: Clique no espaço à esquerda do número 16. Aparecerá uma mancha vermelha pálida ao passar o rato e ficará totalmente vermelha depois de clicar, indicando que um ponto de interrupção foi definido.
- Iniciar depuração: No menu do VS Code, selecione Run / Start Debugging. No seu navegador, recarregue o seu sítio. A sua janela do VS Code deverá reaparecer com o código parado na primeira linha do ficheiro index.php do sítio. No topo do ecrã existem alguns ícones para controlar o processo de depuração. Devem ser autoexplicativos. Caso contrário, consulte-os na Ajuda / Documentação do VS Code.
- Continuar: Selecione o botão continuar — o código avançará até ao seu primeiro ponto de interrupção. Examine o código para ver qual é o problema.
- Passar o rato: Se passar o rato sobre uma variável que tenha um valor atribuído, aparecerá uma pequena dica (Tooltip) a resumir os atributos dessa variável. Não há Tooltip para variáveis que não tenham valores atribuídos.
- Variáveis: A coluna da esquerda contém mais informações sobre a situação do código no ponto de interrupção. Há demasiadas para cobrir aqui. Explore-as conforme necessário!
- Parar depuração: É provavelmente melhor selecionar o ícone Continuar, caso contrário a página web é apresentada em branco. Alternativamente, pode usar o botão Parar ou o menu Run / Stop Debugging.
Corrigir um erro
Lembre-se: Não corrija o erro no código do sítio web! Corrija-o no código-fonte!
Corrija o código-fonte e depois utilize Terminal / Run Build Task....
Reinicie a depuração.
Dicas
Alguns problemas não tão óbvios:
- Corrige o primeiro erro, mas continua a falhar nessa linha. Verifique no ficheiro mod_debugme.xml onde está definido o src das classes com espaço de nomes. Quando corrigido na fonte, precisa de reinstalar o ficheiro zip ou eliminar administrator/cache/autoload_psr4.php. Quando ausente, o Joomla reconstrói esse ficheiro a partir dos ficheiros de manifesto. Mas se este tiver uma entrada incorreta ou em falta, não é corrigido até que a extensão seja reinstalada.
- Por vezes, é necessário definir um ponto de interrupção algumas linhas antes da linha onde ocorre o erro, especialmente se pretender verificar os valores passados a chamadas de função.
- A tabela xxx.yyy\debugme não existe. Ah sim, o código para criar uma tabela na instalação e removê-la na desinstalação nunca foi criado. Terá de executar uma consulta sql no phpMyAdmin utilizando o conteúdo do ficheiro mod\debugme.sql. Lembre-se de alterar #\ nos nomes das tabelas para o prefixo da sua base de dados. E se continuar a falhar, verifique o nome da tabela no código.
Captura de ecrã
Quando tudo estiver corrigido, isto é o que poderá ver:
Cake days?
Referências
Da Documentação do Joomla!: Visual Studio Code também aborda a configuração de outras ferramentas, por exemplo CodeSniffer e PHPUnit.