wp-phpstan

Visão geral da skill wp-phpstan

wp-phpstan é a skill certa quando você precisa que o PHPStan funcione bem em uma base de código WordPress — e não apenas “rode de algum jeito”. Ela é voltada para desenvolvedores de plugins, temas e sites que querem uma análise estática mais limpa, menos falsos positivos e um caminho prático para lidar com código legado que já tem problemas.

A principal tarefa aqui é configuração e correção: ajustar phpstan.neon, lidar com baselines, carregar stubs do WordPress e adicionar anotações de tipos que o WordPress exige quando o PHPStan não consegue inferir o comportamento em tempo de execução.

Para que a wp-phpstan é mais indicada

Use a skill wp-phpstan quando você precisar:

• configurar ou atualizar o PHPStan em um repositório WordPress
• reduzir erros causados pela ausência de símbolos do core do WordPress
• gerenciar phpstan-baseline.neon sem esconder novas regressões
• corrigir padrões dinâmicos do WordPress, como hooks, requests de REST e resultados de query
• lidar com classes opcionais de plugins de terceiros, como WooCommerce ou ACF

Por que esta skill é diferente

Um prompt genérico para PHPStan costuma ignorar restrições específicas do WordPress: classes carregadas em runtime, callbacks de hooks, dependências de plugins e ambientes de análise que não batem com o site em produção. A wp-phpstan é útil porque prioriza esses casos-limite, especialmente o carregamento de stubs e os ignores bem direcionados.

Quando não usar

Se você só precisa de uma explicação rápida e pontual de um comando do PHPStan, esta skill pode ser mais do que você precisa. Ela entrega mais valor quando a qualidade da análise importa o suficiente para que decisões de setup, política de baseline e hints de tipo afetem o resultado.

Como usar a skill wp-phpstan

Instale e verifique a skill

Para wp-phpstan install, adicione a skill a partir do repositório de skills do WordPress agent:

npx skills add WordPress/agent-skills --skill wp-phpstan

Depois da instalação, leia primeiro SKILL.md, e em seguida as referências de apoio e o script de inspeção. O repositório é estruturado para responder às perguntas que mais influenciam a adoção: o que o PHPStan enxerga, o que ele ignora e o que deve ser tipado em vez de suprimido.

Dê à skill as entradas certas

A skill wp-phpstan funciona melhor quando você fornece contexto do projeto antes de pedir correções. Comece com:

• a saída do wp-project-triage
• se as dependências de desenvolvimento do Composer podem ser alteradas
• se é permitido atualizar a baseline
• os erros específicos do PHPStan ou o arquivo de configuração que você quer mudar

Um prompt fraco: “Corrija o PHPStan no meu plugin WordPress.”

Um prompt mais forte: “Use wp-phpstan para inspecionar a configuração atual do PHPStan do meu plugin, confirmar se szepeviktor/phpstan-wordpress está carregado e propor a menor mudança possível de configuração que resolva funções desconhecidas do WordPress sem usar ignores amplos. Mudanças na baseline só são permitidas para erros legados já existentes.”

Fluxo de trabalho sugerido e arquivos

Para um uso prático de wp-phpstan, siga o caminho de decisão do próprio repositório:

1. Inspecione a configuração com scripts/phpstan_inspect.mjs
2. Verifique os arquivos principais de configuração e baseline
3. Revise references/configuration.md
4. Leia references/third-party-classes.md
5. Use references/wordpress-annotations.md quando o problema for inferência de tipos, e não setup

Se você quer o caminho mais rápido para um bom resultado, antecipe estes arquivos:

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

Formato prático de prompt

Prompts bons dizem à skill o que é fixo, o que é flexível e qual resultado você espera. Por exemplo:

• “Faça uma auditoria do meu phpstan.neon para um plugin WordPress e me diga se devo adicionar stubs, apertar ignoreErrors ou atualizar a baseline.”
• “Reescreva esta annotation de controller REST para que o PHPStan entenda o formato da request.”
• “Meu ambiente de análise não inclui WooCommerce; proponha uma estratégia estreita de stub/ignore para essas classes ausentes.”

Esse nível de detalhe ajuda a wp-phpstan a escolher entre mudanças de configuração, anotações ou alterações de dependência.

Perguntas frequentes sobre a skill wp-phpstan

A wp-phpstan é só para plugins WordPress?

Não. A skill wp-phpstan também se encaixa em temas e em sites WordPress com código customizado. Ela é mais útil em qualquer lugar onde o PHPStan precise de ajuda para entender o comportamento de runtime do WordPress.

Preciso já ter Composer e PHPStan instalados?

Sim. Esta skill pressupõe um fluxo de trabalho com PHPStan baseado em Composer. Se o seu repositório não usa Composer, ou se o PHPStan não faz parte da ferramenta de desenvolvimento, esta skill não é uma boa escolha.

Isso é melhor do que escrever um prompt customizado?

Geralmente sim, se você se importa com decisões de setup reproduzíveis. Um prompt customizado pode resolver um erro isolado, mas a wp-phpstan oferece um fluxo melhor para baselines, stubs e tipagem específica de WordPress.

Quando devo evitar ignores amplos?

Evite ignores amplos quando a classe ou função realmente existe, mas está ausente por causa de um stub faltando, de um problema de autoload ou de uma divergência entre o ambiente de análise e o ambiente real. Use ignores direcionados só depois de verificar que o caminho da dependência é real e não pode ser corrigido de forma limpa.

Como melhorar a skill wp-phpstan

Informe o modo real de falha do PHPStan

Os melhores resultados com wp-phpstan vêm de identificar o tipo de falha antes de pedir a correção:

• funções desconhecidas do core do WordPress → stubs ou configuração
• ruído legado → fluxo de baseline
• dados dinâmicos de request → @phpstan-param ou aliases de tipo reutilizáveis
• APIs opcionais de plugins → stubs direcionados ou ignores estreitos

Se você apenas colar uma lista de erros, a skill pode otimizar o sintoma em vez da causa.

Compartilhe a fronteira da análise

Diga à skill o que ela pode alterar. Os resultados melhoram quando você especifica:

• ela pode editar composer.json?
• ela pode adicionar dependências de desenvolvimento?
• ela pode alterar phpstan.neon?
• ela pode regenerar a baseline?

Essas permissões determinam se wp-phpstan deve priorizar correções de código, de configuração ou de dependência.

Prefira entradas concretas a objetivos genéricos

Entrada mais forte gera saída melhor. Por exemplo, inclua:

• o nível atual do PHPStan
• os diretórios que você analisa
• se o core do WordPress está presente no CI
• o plugin ou a classe exata que está gerando erros de símbolo ausente

Isso ajuda a skill wp-phpstan a recomendar o caminho certo de instalação e uso para Backend Development, em vez de devolver um checklist genérico de PHPStan.

Itere de configuração para anotações

Um bom guia de wp-phpstan normalmente segue esta ordem:

1. verificar stubs e descoberta
2. restringir excludes e ignores
3. anotar tipos dinâmicos específicos do WordPress
4. atualizar a baseline só para a dívida legada aceita

Essa ordem mantém a análise rígida o bastante para pegar problemas novos, ao mesmo tempo em que reduz falsos positivos onde o modelo dinâmico do WordPress impede a inferência.