PHP Toolkit

Extensão "tudo em um" para PHP no VS Code:

• Lint — roda php -l (via stdin) a cada alteração/salvamento e mostra erros de sintaxe como diagnostics nativos do VS Code.
• PHPDoc — gera blocos /** ... */ para funções, métodos, classes e propriedades:
  • Comando "PHP Toolkit: Generate PHPDoc Block" (atalho Ctrl+Alt+D / Cmd+Alt+D), executado com o cursor na linha (ou logo acima) da declaração.
  • Auto-expansão ao digitar /** e pressionar Enter imediatamente acima de uma função/classe/propriedade (heurística best-effort — valide no seu ambiente).
• Namespace Resolver — indexa todas as classes/interfaces/traits/enums do workspace (**/*.php, ignorando vendor/node_modules) e:
  • "PHP Toolkit: Import Class Under Cursor" (Ctrl+Alt+I / Cmd+Alt+I) — insere o use correto para a classe sob o cursor (quick fix também disponível via lightbulb).
  • "PHP Toolkit: Import All Unresolved Classes" — varre o arquivo e importa tudo que conseguir resolver sem ambiguidade.
  • "PHP Toolkit: Sort Use Statements" — ordena e deduplica o bloco de use.
• Debug (Xdebug) — debugger completo via protocolo DBGp, registrado como tipo php-toolkit no launch.json:
  • attach — apenas escuta uma porta (padrão 9003) e aguarda o Xdebug se conectar (fluxo típico com servidor web: configure xdebug.mode=debug, xdebug.start_with_request=yes, xdebug.client_port=9003 no php.ini e dispare uma requisição no navegador).
  • launch — executa um script PHP via CLI (program) já com as flags do Xdebug injetadas automaticamente.
  • Suporta breakpoints de linha (com condição), exception breakpoints ("Uncaught Exceptions/Errors"), step in/over/out, pause, call stack, inspeção de variáveis (incluindo arrays/objetos aninhados) e evaluate no Debug Console/watch.
  • pathMappings — necessário quando o PHP roda em outro filesystem que o VS Code enxerga (ex.: VS Code nativo no Windows + PHP dentro do WSL/Docker). Exemplo:

    "pathMappings": [
      { "serverPath": "/home/kenny/phpVsCode", "localPath": "\\\\wsl.localhost\\Ubuntu\\home\\kenny\\phpVsCode" }
    ]
    

Use o menu "Run and Debug" → "create a launch.json file" e escolha um dos snippets PHP Toolkit: ... para começar.

• PHPUnit — integra com a aba nativa Testing do VS Code:
  • Descobre classes/métodos de teste (extends TestCase, métodos testXxx, @test/#[Test]) via phptoolkit.phpunit.testFilePattern (padrão **/*Test.php).
  • Botões ▶ Run e 🐛 Debug por método/classe/arquivo/tudo, direto no editor (CodeLens) ou na aba Testing.
  • "Run" executa phpunit --log-junit e faz o parse do relatório para reportar pass/fail com a mensagem de falha; "Debug" abre uma sessão php-toolkit (reaproveitando o debugger Xdebug) rodando o vendor/bin/phpunit.
  • Detecta vendor/bin/phpunit automaticamente; configure phptoolkit.phpunit.phpunitPath se usar outro caminho.
• Debug multi-conexão — o debugger suporta várias conexões Xdebug simultâneas (ex.: múltiplas requisições web em paralelo); cada uma aparece como uma "thread" separada no painel Run and Debug, com sua própria call stack/variáveis/step control.
• PHP_CodeSniffer (phptoolkit.phpcs.enable, desligado por padrão) — diagnostics de padrão de código via phpcs --report=json (stdin, ao vivo). Configure phptoolkit.phpcs.standard (ex. PSR12) ou deixe vazio para usar o phpcs.xml do projeto.
• PHPStan (phptoolkit.phpstan.enable, desligado por padrão) — roda phpstan analyse --error-format=json no save (precisa de arquivo salvo + autoload do projeto). Configure phptoolkit.phpstan.level ou use o phpstan.neon.
• PHP-CS-Fixer (phptoolkit.csFixer.enable, desligado por padrão) — habilita "Format Document" para PHP via php-cs-fixer fix; usa .php-cs-fixer(.dist).php do projeto se existir, senão phptoolkit.csFixer.rules (padrão @PSR12).
• Composer helpers — comandos "PHP Toolkit: Run Composer Script" (lista scripts do composer.json e roda no terminal) e "PHP Toolkit: Composer Require" (prompt de pacote, produção ou --dev).
• Verificação PSR-4 (phptoolkit.psr4Check.enable, ligado por padrão) — avisa quando o namespace de um arquivo não bate com o autoload psr-4 do composer.json, com quick fix para corrigir.
• Refatorações (cursor dentro de uma classe):
  • "PHP Toolkit: Generate Constructor from Properties" — monta __construct a partir das propriedades tipadas já declaradas.
  • "PHP Toolkit: Generate Getters/Setters" — na propriedade sob o cursor, ou escolha múltipla via quick pick; pula setter em propriedades readonly.
  • "PHP Toolkit: Implement Missing Interface/Abstract Methods" — lê implements/extends, resolve via o índice de namespaces, e gera stubs (throw new \RuntimeException(...)) para o que faltar.
• Navegação — "Go to Definition" (F12), "Find All References" (Shift+F12, busca textual por nome no workspace) e hover em nomes de classe/interface/trait/enum, resolvidos pelo mesmo índice do Namespace Resolver.
• Outline/breadcrumbs — classes, propriedades e métodos aparecem no painel Outline e nos breadcrumbs do editor.
• "PHP Toolkit: New PHP Class/Interface/Trait/Enum" — disponível na Command Palette ou clique-direito numa pasta do Explorer; já preenche o namespace correto lendo o autoload.psr-4 do composer.json.
• "PHP Toolkit: Extract Interface from Class" — gera uma nova interface a partir dos métodos públicos da classe sob o cursor, com opção de já adicionar implements na classe original.
• Servidor embutido do PHP no debug — configuração launch com serve: { docroot, port } sobe php -S com Xdebug habilitado, sem precisar de Apache/Nginx (veja o snippet "Launch built-in PHP server").
• Snippets — construtor com propriedades promovidas, match, try/catch, foreach, enum com backing, método de teste PHPUnit, etc. (snippets/php.json).
• Rename Symbol (F2) — renomeia uma classe/interface/trait/enum em todo o workspace (busca textual, mesma limitação de precisão do Find References) e, se o arquivo tiver o mesmo nome da classe (convenção PSR-4), já renomeia o arquivo junto. O VS Code mostra um preview multi-arquivo antes de aplicar.
• Autocomplete com auto-import — ao digitar o começo de um nome de classe conhecida no workspace, a sugestão já insere o use correto ao aceitar (igual ao "Import Class", só que proativo).
• Autocomplete de pacotes do Packagist — dentro de require/require-dev no composer.json, sugere nomes de pacotes reais consultando a API do packagist.org (phptoolkit.composer.packagistCompletion, ligado por padrão — desligue se não quiser chamadas de rede).
• "PHP Toolkit: Run Console Command (Artisan/Symfony)" — detecta artisan (Laravel) ou bin/console (Symfony) na raiz do workspace e roda o comando digitado num terminal.
• Checagem de .env (phptoolkit.env.enable, desligado por padrão) — avisa quando env('CHAVE') no código PHP referencia uma chave ausente em .env/.env.example.
• "PHP Toolkit: Toggle declare(strict_types=1)" — adiciona/remove a declaração logo após <?php.
• "PHP Toolkit: Generate PHPDoc Blocks for Entire File" — documenta de uma vez todas as classes/métodos/propriedades do arquivo que ainda não têm docblock.
• Visualização de profiling do Xdebug — parser do formato cachegrind + painel interativo (tabela ordenável, com filtro por nome) mostrando self time/inclusive time, memória e número de chamadas por função:
  • "PHP Toolkit: Profile Current PHP Script" — roda o arquivo aberto via CLI com xdebug.mode=profile, acha o cachegrind.out.* gerado e já abre o painel.
  • "PHP Toolkit: Open Xdebug Profile (Cachegrind)..." — abre um arquivo cachegrind.out.* já existente (ex.: gerado por uma requisição web real com o profiler do Xdebug habilitado no php.ini). Também aparece no clique-direito de arquivos cachegrind.out.* no Explorer.
  • phptoolkit.profiler.outputDir configura onde o "Profile Current PHP Script" escreve o arquivo (padrão: pasta temp nova a cada execução).

Rodando em modo de desenvolvimento

1. npm install
2. Abra a pasta no VS Code e pressione F5 (roda a task watch e abre um Extension Development Host).
3. No host, abra sample/Sample.php e teste:
   • Introduza um erro de sintaxe (ex.: remova um ;) e veja o diagnostic aparecer.
   • Posicione o cursor acima de um método sem docblock e rode o comando ou o atalho.

Configurações (phptoolkit.*)

Limitações conhecidas

• Ao desmarcar/mover um breakpoint de linha já ativo numa sessão em andamento, o novo estado é reenviado ao Xdebug, mas o breakpoint antigo não é explicitamente removido do engine (breakpoint_remove) — na prática costuma ser inofensivo (a linha antiga simplesmente não existe mais no arquivo salvo), mas pode causar um breakpoint "fantasma" em cenários de edição bem específicos.
• PHPStan só analisa o arquivo salvo em disco (não em tempo real como o lint), porque precisa do autoload real do projeto.
• O parser de classes (refatorações, PHPUnit discovery, PHPDoc) é baseado em regex/heurística, não um parser PHP completo — cobre o estilo comum de código, mas construções incomuns (ex. chaves {/} dentro de strings/heredocs) podem confundir a detecção de limites de classe.

Build/Empacotamento

• npm run compile — bundle único via esbuild (dist/extension.js).

• npm run check-types — checagem de tipos TypeScript.

• npx @vscode/vsce package --no-dependencies — gera o .vsix instalável.

  A flag --no-dependencies é necessária (não opcional) neste projeto: sem ela, o vsce tenta descobrir dependências rodando npm list --production como subprocesso, e isso está quebrado neste ambiente — o resultado é sempre ERROR Extension entrypoint(s) missing, mesmo com dist/extension.js existindo. Como todas as dependências (@vscode/debugadapter, fast-xml-parser, etc.) já vão embutidas dentro do dist/extension.js pelo esbuild, essa flag é na real o jeito correto de empacotar aqui, não só um workaround.

  Se a pasta do projeto for um caminho UNC do WSL (\\wsl.localhost\...), rode esses comandos via PowerShell, não via Git Bash — o npm no Windows é um .cmd, e quando o Node precisa invocar um subprocesso de shell (ex.: no script vscode:prepublish), ele usa cmd.exe, que não aceita UNC como diretório de trabalho e cai silenciosamente em C:\Windows. Rodar de dentro do PowerShell evita isso na maioria dos casos; se mesmo assim algum subcomando falhar com esse erro, copie a pasta pra um caminho nativo do Windows (robocopy) ou mapeie uma letra de unidade (subst P: \\wsl.localhost\...) e rode o vsce package de lá.