PHPMX JSON Docblock

Orgulhosamente feito para PHP.

Nasceu dentro do ecossistema do PHPMX para ser utilizada por todos.

Documente estruturas de dados JSON diretamente nos docblocks (/** ... */) do PHP. A extensão oferece highlighting semântico, validação em tempo real, autocompletion entre arquivos e formatação automática.

Leve e inerte: A extensão não interfere no runtime do PHP e não gera arquivos externos. Ela atua puramente como uma ferramenta de DX (Developer Experience) no seu editor.

⚡ Recursos em Destaque

🎨 Highlighting Semântico: Cores precisas para tags, tipos primitivos, campos e referências.
🌐 Tipos Globais no Workspace: @type definidos em qualquer .php são indexados automaticamente.
🔍 Navegação Rápida: Suporte a Ctrl+Click (Go to Definition) e Hover para inspecionar schemas de outros arquivos.
✨ Formatação Inteligente: Formata ao salvar (formatOnSave) sem quebrar os asteriscos (*) do docblock PHP.
⚠️ Validação em Tempo Real: Alertas para tipos inexistentes, nomes duplicados e tipos inválidos para JSON (Closure, resource, etc.).

📖 Sintaxe Rápida

Recurso	Sintaxe	Exemplo	Descrição
Declaração	`@type NOME { ... }`	`@type USER { id: int }`	Registra um tipo global reutilizável
Uso Local	`@tag { ... }`	`@response { data: USER }`	Descreve o shape no ponto de uso
Opcional	`campo?:`	`nickname?: string`	O campo pode não existir no payload
Nullable	`?tipo` ou `tipo\\|null`	`avatar: ?string`	A chave existe, mas o valor aceita `null`
Union	`tipo1\\|tipo2`	`id: int\\|string`	Aceita múltiplos tipos
Literal	`valor`	`status: 200\\|201`	Aceita apenas o valor exato
Array	`tipo[]`	`tags: string[]`	Lista tipada (suporta matrizes `tipo[][]`)
Default	`campo: tipo = val`	`page: int = 1`	Valor padrão para entradas (torna o campo opcional)
Comentário	`// texto`	`id: int // ID único`	Sempre `//`. Nunca `/* */` (fecha o docblock antes da hora)

Exemplos Práticos

1. Declarando tipos reutilizáveis (src/Docs/Types.php)

/**
 * @type ADDRESS {
 *   street: string
 *   city: string
 *   zipCode: string
 * }
 *
 * @type USER {
 *   id: int|string // ID numérico ou UUID
 *   name: string
 *   avatar: ?string // Pode ser null
 *   active?: bool // Campo opcional
 *   address: ADDRESS // Referência a outro @type
 *   tags: string[]
 * }
 */

2. Usando em um Controller (src/Controllers/UserController.php)

final class UserController
{
    /**
     * @response {
     *   status: 200
     *   data: USER[]
     * }
     */
    public function index(): array
    {
        // ...
    }

    /**
     * Tipos com hífen funcionam como pseudo-namespaces
     *
     * @type AUTH-PAYLOAD {
     *   token: string
     *   expiresIn: int
     * }
     *
     * @response {
     *   status: 200
     *   data: AUTH-PAYLOAD
     * }
     */
    public function login(): array
    {
        // ...
    }
}

3. Nullable, opcional e union

/**
 * @response {
 *   status: 200|201
 *   data: USER|null
 *   note: ?string      // sempre vem, mas pode ser null
 *   warning?: string   // pode nem vir na resposta
 * }
 */

4. Valor padrão para entrada (query/params)

/**
 * @type LIST-QUERY {
 *   page: int = 1
 *   perPage: int = 20
 *   sort: string = "created_at"
 *   onlyActive: bool = true
 * }
 */

5. Exemplo quebrado, pra ver a validação em ação

/**
 * @response {
 *   status: 200
 *   data: NAO_EXISTE     // tipo não existe em lugar nenhum do workspace
 *   data: USER           // campo duplicado
 *   callback: Closure    // não é serializável em JSON
 * }
 */

⚙️ Configurações

Adicione ao seu .vscode/settings.json para ajustar os arquivos monitorados:

{
  "phpmxJsonDocblock.include": "**/*.php",
  "phpmxJsonDocblock.exclude": "**/{vendor,node_modules,.git}/**",
  "phpmxJsonDocblock.formatOnSave": true
}

📌 Comandos Disponíveis

PHPMX JSON Docblock: Format Block At Cursor: reformata apenas o bloco atual.
PHPMX JSON Docblock: Show Known @type Definitions: lista todas as definições @type indexadas no workspace.

ℹ️ Escopo e Limitações

O que ela faz: Validação estrutural de sintaxe, autocompletion, navegação e formatação visual do docblock.
O que ela não faz: Não interfere no runtime do PHP, não valida retornos em tempo de execução e não gera nenhum artefato ou schema por conta própria. Essas tarefas cabem a outra ferramenta, fora daqui.