User Documentation VS Code - Um IDE Gratuito Popular
Da Wikipédia:
O Visual Studio Code, também comumente chamado de VS Code, é um editor de código-fonte criado pela Microsoft para Windows, Linux e macOS. Os recursos incluem suporte para depuração, destaque de sintaxe, conclusão inteligente de código, trechos de código, refatoração de código e Git incorporado. Os usuários podem alterar o tema, atalhos de teclado, preferências, e instalar extensões que adicionam funcionalidades extras.
Instalação
A página padrão do site do VS Code possui uma lista suspensa para cada plataforma suportada. É provável que sua plataforma já esteja pré-selecionada. Então basta baixar e instalar e você já está pronto para começar.
Começando
A página Get Started do VS Code possui alguns itens de Start, uma lista de itens Recent, e uma pequena lista de Walkthroughs. Se você é totalmente novo no VS Code, é recomendável assisti-los. Eles levam apenas alguns minutos.
A documentação do VS Code está disponível no menu Help / Documentation. Os Vídeos Introdutórios valem muito a pena assistir. Cada um leva de 2 a 6 minutos e oferece uma excelente introdução aos recursos do VS Code.
A documentação oficial é o lugar certo para consultar informações específicas.
Extensões do VS Code
O VS Code pode ser usado para qualquer tipo de texto, incluindo uma ampla gama de linguagens de programação. Ele funciona com JavaScript sem a necessidade de adicionar extensões. Outras linguagens são detectadas pelo contexto, então, se você começar a criar e salvar código PHP, provavelmente será solicitado a instalar um pacote de suporte PHP.
Clique no ícone Extensions na Activity Bar à esquerda para ver o que você já tem instalado e o que é recomendado. Você precisará da extensão PHP Debug!
O Layout de Tela do VS Code
Alguns termos usados nas instruções a seguir:
- Activity Bar a barra estreita à esquerda da tela. Selecionar qualquer ícone para abrir ou fechar a Primary Sidebar.
- Primary Side Bar quando aberta, exibe detalhes da atividade selecionada.
- Status Bar na parte inferior da tela. Exibe o que está acontecendo.
- Panel uma área abaixo dos editores de texto para exibir outras informações.
Selecionar um ícone de layout no canto superior direito para abrir ou fechar qualquer um desses itens.
Codificando uma Extensão Joomla
Para criar uma extensão, seu objetivo é criar um arquivo zip que possa ser instalado em um site Joomla em funcionamento. Então você precisa de uma pasta para conter seu código. Ela deve estar dentro do seu espaço de arquivos pessoal no laptop ou computador de mesa usado para desenvolvimento local. Não deve estar na árvore do seu site. Por exemplo, você poderia usar ~/jextensions para conter subpastas para diferentes extensões. Eu uso ~/git porque é curto e fácil de digitar, embora possa ser confuso, já que cada subpasta usa um repositório git separado.
Código de Exemplo
Se você gostaria de ter algum código de exemplo para trabalhar, há uma extensão disponível no GitHub chamada mod_debugme. Como o nome sugere, é um módulo com alguns bugs. Além do código do módulo, há um arquivo build.xml para ilustrar uma forma de automatizar a construção para testes e criação de um arquivo zip.
O módulo foi projetado para exibir os próximos eventos (aniversários, por padrão 3) de uma lista armazenada em uma tabela de banco de dados. Você pode imaginar isso sendo usado em um escritório ou site familiar na expectativa de bolo.
Pode ser melhor começar usando comandos git na linha de comando. Primeiro crie uma pasta para o seu código e então clone o repositório remoto:
mkdir ~/git
cd ~/git
git clone https://github.com/ceford/j4xdemos-mod-debugme
A resposta deve levar 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.
Você deve dedicar um momento para examinar 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 arquivo README.md é um documento markdown que descreve este repositório. O arquivo build.xml é um arquivo usado para compilar a extensão com uma ferramenta externa, o Phing - descrita mais adiante. A pasta mod_debugme contém o código da extensão.
Instalar no Joomla
Compacte a pasta da extensão para criar um arquivo zip instalável:
zip -r mod_debugme.zip mod_debugme
Agora você pode instalar o arquivo zip no site Joomla que você usa para testes. Após a instalação, você precisa criar um módulo de site e atribuí-lo a uma posição de módulo. Como se trata de um módulo com defeito proposital, você pode atribuí-lo a uma posição em Todas as páginas enquanto trabalha nele; ou pode atribuí-lo a uma posição em uma única página; ou pode posicioná-lo em um artigo que tenha seu próprio item de menu.
Após a instalação, exclua o arquivo zip.
Ativar o modo de depuração
Nas Configurações Globais do Joomla, defina Sistema de Depuração como Sim e Relatório de Erros como Máximo.
Ao abrir uma página que contenha o módulo com defeito, você verá um stack trace informando onde um erro foi acionado.
Às vezes o erro de codificação está na primeira linha do stack trace. Caso contrário, se o erro for acionado em código de biblioteca, por exemplo ao passar dados inválidos para uma função de banco de dados, o erro de codificaçã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 Arquivo / Abrir Pasta para localizar e abrir a pasta que contém sua cópia local do código da extensão mod_debugme. Você deve ver algo semelhante ao seguinte:
Você pode conseguir diagnosticar o problema apenas lendo o código. No caso do erro Class "DebugHelper" not found, você 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 então compacte e instale o módulo novamente. Esse passo fica um pouco cansativo quando você tem vários problemas. É aí que as ferramentas de build se tornam úteis.
Phing
Phing é uma ferramenta de linha de comando, disponível para todas as plataformas, usada para construir pacotes de software usando instruções armazenadas em um arquivo xml, chamado build.xml por padrão. Para trabalhar com o código de uma extensão, ela pode ser usada para fazer duas coisas:
- copiar arquivos alterados da pasta de origem da sua extensão para os lugares corretos na pasta do seu site.
- gerar um novo arquivo zip para novas instalações.
Baixe e instale o Phing. Outras ferramentas de build estão disponíveis! Você pode instalar o Phing na sua própria pasta bin ou em uma pasta bin do sistema. Você precisa anotar o caminho para o código do Phing. Neste exemplo é ~/bin/phing-latest.phar. Você pode testá-lo a partir da linha de comando depois de entrar na 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 de dentro do VS Code, você precisa criar um arquivo tasks.json na pasta .vscode na raiz da pasta j4xdemos-mod-debugme. Se esta última não existir, crie-a primeiro. Em seguida, crie o arquivo 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"
}
}
]
}
Usuários do Windows precisam corrigir o comando específico do Windows. Agora você pode construir a extensão usando o menu Terminal / Run Build Task. O resultado do comando deve 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 arquivo build.xml ou uma pasta que não foi criada. Apenas mais um tipo de problema para depurar!
Depuração
Você deve conseguir corrigir o primeiro bug por inspeção do código. Problemas mais complicados exigem percorrer o código passo a passo com o depurador. Isso permite que você inspecione variáveis para ver se elas contêm os valores esperados, por exemplo, ao passar argumentos para funções de biblioteca.
Configurações do php.ini
Para configurar a depuração com o Xdebug, você precisa fazer algumas entradas no topo do seu arquivo php.ini.
zend_extension="xdebug.so"
xdebug.mode="debug"
xdebug.client_port=9003
xdebug.start_with_request = yes
Depois de salvar as alterações, reinicie seu servidor Apache.
Janela Adicionar site
Sua pasta de extensão contém apenas alguns arquivos, os fontes dos arquivos instalados no seu site. A depuração em tempo de execução envolve definir pontos de interrupção nos arquivos do site, portanto você precisa ter acesso a esses arquivos. Você poderia usar o menu File / Add Folder to Workspace... para adicionar a pasta do site ao seu Workspace. No entanto, há uma grande chance de você acabar fazendo alterações nos arquivos do site em vez dos arquivos de origem. Portanto, é provavelmente melhor abrir uma janela separada do VS Code para a depuração.
- Abrir nova janela: No menu do VS Code, selecione File / New Window e selecione a pasta que contém o seu site Joomla.
- Abrir pasta: Na janela recém-aberta, selecione File / Open Folder... no menu do VS Code. Encontre a pasta do seu site e selecione-a. Você deverá ver uma lista de todos os arquivos do seu site Joomla na barra lateral principal.
Configuração de inicialização
Para que a depuração funcione de fato no VS Code, você precisa de uma configuração de inicialização. Na raiz do seu site, crie uma pasta chamada .vscode (observe o ponto inicial) contendo um arquivo chamado 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 site. O item stopOnEntry irá pausar a execução na primeira linha de código PHP executada.
Depurar mod_debugme
Agora você está pronto para encontrar e corrigir os bugs no módulo instalado.
- Encontrar o código do módulo: Encontre o primeiro bug 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. Uma mancha vermelha clara aparecerá ao passar o mouse e ficará totalmente vermelha após o clique, 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 site. Sua janela do VS Code deverá reaparecer com o código parado na primeira linha do arquivo index.php do site. No topo da tela há alguns ícones para controlar o processo de depuração. Eles devem ser autoexplicativos. Caso contrário, procure por eles na Ajuda / Documentação do VS Code.
- Continuar: Selecione o botão continuar - o código será executado até o seu primeiro ponto de interrupção. Examine o código para ver qual é o problema.
- Passar o mouse: Se você passar o mouse sobre uma variável que recebeu um valor, uma pequena dica de ferramenta aparecerá resumindo os atributos dessa variável. Não há dica de ferramenta para variáveis que não receberam valores.
- Variáveis: A coluna à esquerda contém mais informações sobre o estado do código no ponto de interrupção. Há muitas para cobrir aqui. Explore-as conforme necessário!
- Parar a depuração: Provavelmente é melhor selecionar o ícone Continuar, caso contrário a página web é entregue em branco. Caso contrário, você pode usar o botão Parar ou o menu Executar / Parar depuração.
Corrigir um bug
Lembre-se: Não corrija o bug no código do site! Corrija-o no código-fonte!
Corrija o código-fonte e então use Terminal / Executar tarefa de compilação....
Reinicie a depuração.
Dicas
Alguns problemas não tão óbvios:
- Você corrige o primeiro bug, mas ele ainda falha naquela linha. Verifique em mod_debugme.xml onde o src das classes com namespace está definido. Quando corrigido na fonte, você precisa reinstalar o arquivo zip ou excluir administrator/cache/autoload_psr4.php. Quando ausente, o Joomla reconstrói esse arquivo a partir dos arquivos de manifesto. Mas se houver uma entrada incorreta ou ausente, ela não é corrigida até que a extensão seja reinstalada.
- Às vezes você precisa definir um ponto de interrupção algumas linhas antes da linha onde o erro ocorre, especialmente se quiser verificar valores passados para 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. Você precisará executar uma consulta sql no phpMyAdmin usando o conteúdo do arquivo mod\debugme.sql. Lembre-se de alterar #\ nos nomes das tabelas para o prefixo do seu banco de dados. E quando ainda assim falhar, verifique o nome da tabela no código.
Captura de tela
Quando tudo estiver corrigido é isto que você pode ver:
Dia de comemorar?
Referências
Da Documentação do Joomla!: Visual Studio Code também aborda a configuração de outras ferramentas, por exemplo CodeSniffer e PHPUnit.