Desenvolvimento Local

Guia de setup para desenvolvimento local do plugin WordPress middag-account.

Requisitos

Ferramenta	Versão	Observações
PHP	8.4+	Com extensões: curl, decimal, dom, intl, json, mbstring, openssl, simplexml, soap, xml, zip
Composer	2.x	Gerenciamento de dependências
Node.js	20+	Build da UI React
npm	10+	Gerenciamento de pacotes
WordPress	6.5+	Instalação local
WooCommerce	9.0+	Dependência obrigatória do plugin
MySQL	8.0+	Ou MariaDB 10.6+

Setup Inicial

# Clone em wp-content/plugins/
cd wp-content/plugins/middag-account

# Instalar dependências PHP
composer install

# Instalar dependências Node e blocos ReUI
composer ui:setup

# Build da UI React (Vite -> assets/dist/app.js)
composer ui:npm:build

Estrutura do Projeto

middag-account/
├── src/               # Código-fonte PHP (PSR-4: Middag\Account\)
│   ├── Core/          # Container, Kernel, ServiceProvider
│   ├── Domain/        # Lógica de domínio PHP puro (zero deps WP)
│   ├── Api/V1/        # REST controllers
│   ├── Integration/   # Adaptadores de serviços externos
│   ├── WordPress/     # Camada de abstração WP
│   └── UI/            # Inertia page controllers
├── tests/             # Testes PHPUnit (espelha src/)
├── ui/                # React 19 + Inertia.js + Tailwind v4
├── assets/dist/       # Output do frontend compilado
├── docs/              # ADRs, casos de uso, operações
└── docs-site/         # Documentação de referência para desenvolvedores

Executando Testes

# Executar suite completa de testes
composer test

# Executar um arquivo de teste específico
./vendor/bin/phpunit tests/Unit/Domain/Entitlement/EntitlementServiceTest.php

# Executar testes com relatório de cobertura
./vendor/bin/phpunit --coverage-html coverage/

A estrutura de testes espelha src/:

• tests/Unit/Domain/{Name}/ -- Testes unitários de domínio (Brain\Monkey para stubs WP)
• tests/Integration/{Feature}/ -- Testes de integração com bootstrap WP

Análise Estática

# Executar todas as verificações de qualidade (style + rector + phpstan)
composer check

# Correção automática de estilo e aplicação do rector
composer fix

Ferramentas individuais:

# PHP-CS-Fixer
./vendor/bin/php-cs-fixer fix --dry-run --diff

# PHPStan (nível 6+)
./vendor/bin/phpstan analyse

# Rector
./vendor/bin/rector process --dry-run

Desenvolvimento de UI

# Instalar dependências de frontend
composer ui:setup

# Build do bundle de produção (Vite IIFE -> assets/dist/app.js)
composer ui:npm:build

# Modo de desenvolvimento com hot reload
cd ui && npm run dev

A UI utiliza React 19 + Inertia.js v2 + Tailwind v4 com o design system @middag-io/react. O Vite 6 gera um bundle IIFE consumido pelo WordPress.

Leia ui/DESIGN.md antes de fazer qualquer alteração visual ou de UI.

Internacionalização

# Gerar template de tradução .pot
composer i18n:pot

# Compilar arquivos .mo a partir das traduções .po
composer i18n:mo

Text domain: middag-account. Idioma de origem: inglês. Todas as strings voltadas ao usuário devem usar __(), _e() ou esc_html__().

Build de Distribuição

# Build completo: check + i18n + ui:build + composer --no-dev
composer dist:build

Isso produz um ZIP limpo, sem dependências de desenvolvimento, arquivos de teste ou documentação.

Variáveis de Ambiente

O plugin carrega variáveis de ambiente via vlucas/phpdotenv. Crie um arquivo .env na raiz do plugin (ignorado pelo git):

MIDDAG_JWT_PRIVATE_KEY_PATH=/path/outside/webroot/private.pem
MIDDAG_JWT_PUBLIC_KEY_PATH=/path/outside/webroot/public.pem
STRIPE_WEBHOOK_SECRET_BR=whsec_...
STRIPE_WEBHOOK_SECRET_GLOBAL=whsec_...
HUBSPOT_CLIENT_SECRET_BR=...
HUBSPOT_CLIENT_SECRET_GLOBAL=...

Chaves privadas devem ser armazenadas fora do webroot.

Resumo de Comandos Úteis

Comando	Descrição
composer test	Executar suite de testes PHPUnit
composer check	Style + Rector + PHPStan
composer fix	Correção automática de style + Rector
composer ui:setup	npm install + blocos ReUI
composer ui:npm:build	Build React -> assets/dist/
composer i18n:pot	Gerar arquivo .pot
composer i18n:mo	Compilar arquivos .mo
composer dist:build	Build completo de distribuição

Relacionados

• Visão Geral da Arquitetura -- Design do sistema
• Modelo de Dados -- Estrutura de CPT e persistência