PHP MVCDOCUMENTAÇÃO
v2.0.0

Instalação

Requisitos e passos mínimos para executar a aplicação.

Requisitos

  • PHP 8.1 ou superior.
  • Composer para instalar as dependências declaradas.
  • MySQL acessível e extensão PDO MySQL.
  • Extensões PHP utilizadas pelos recursos correspondentes: cURL (ApiClient), Fileinfo (validação de MIME de uploads) e mbstring (validação/normalização textual).

As dependências Composer obrigatórias são vlucas/phpdotenv e phpmailer/phpmailer. PHPUnit está declarado como dependência de desenvolvimento.

Instalação

composer create-project elias-antonio/php-mvc php-mvc
cd php-mvc

# O post-create copia .env.example para .env; composer create-project cuida da instalação.
# Ajuste .env e crie o banco MySQL antes de migrar.
php mvc key:generate
php mvc list
php mvc migrate
php mvc serve

O manifesto declara o binário mvc; nos exemplos, o comando é executado como php mvc a partir da raiz do projeto.

Configurar e iniciar

  1. Crie o banco MySQL e ajuste o .env conforme Configuração.
  2. Configure APP_ENV=local e APP_URL=http://localhost:8000.
  3. Execute php mvc migrate para aplicar migrations pendentes.
  4. Inicie com php mvc serve ou composer serve.
  5. Abra http://localhost:8000.
php mvc migrate
php mvc serve --port=8080
Produção: APP_URL precisa estar definida como URL HTTP(S) absoluta válida. Não exponha APP_DEBUG em produção; a configuração força debug desligado nesse ambiente.

Testes

O manifesto fornece composer test, que executa PHPUnit. Instale as dependências de desenvolvimento antes de usar esse comando.

Instalar sem sobrescrever configuração existente

O manifesto Composer registra um script pós-criação que copia .env.example para .env. Em uma criação normal do pacote, confira se esse arquivo já apareceu antes de copiá-lo manualmente; não substitua um .env que já contenha valores próprios.

composer create-project elias-antonio/php-mvc php-mvc
cd php-mvc

# O post-create-project-cmd cria .env. Confira antes de copiar manualmente.
php mvc list
php mvc key:generate

O binário mvc fica declarado no Composer; os exemplos usam php mvc na raiz. `key:generate` exige que .env exista e atualiza APP_KEY. Crie o database MySQL antes da primeira migração e ajuste as variáveis em Configuração.

Verificação por etapas

VerificaçãoComando / açãoO que confirma
CLI respondephp mvc listKernel encontrou o binário e os comandos
Conexão e schemaphp mvc migrateCredenciais, PDO MySQL e migrations
Entrada webphp mvc serveServidor local disponível em localhost
Suíte de testescomposer testDependências de desenvolvimento instaladas
`php mvc migrate` aplica migrations pendentes, mas não cria as credenciais do banco por você. `migrate --fresh` apaga/recria o banco configurado: não use como passo rotineiro nem em dados que precisam ser preservados.

Se o processo PHP não puder gravar em storage/, confira permissões de logs, sessões, cache de rate limit e uploads. Para produção, configure o servidor para servir apenas public/ e encaminhar rotas não existentes ao front controller; não exponha a raiz do projeto.

Limitações do servidor local e sincronização de URL

O comando php mvc serve inicia o servidor embutido como php -S host:port -t public; ele não passa public/index.php como router script. Portanto, o PHP serve arquivos existentes, mas não encaminha automaticamente URLs amigáveis como /auth/login e /dashboard para o front controller. A home pode abrir enquanto links para rotas não correspondentes a arquivos falham.

Para testar essas rotas, use um servidor local configurado para encaminhar requisições não-arquivo a public/index.php, ou adote conscientemente um router script compatível. Não interprete a execução bem-sucedida de serve como suporte completo a rewrite.

APP_URL é independente da porta informada ao comando. Se usar php mvc serve --port=8080, ajuste a configuração para APP_URL=http://localhost:8080 (e mantenha host/protocolo consistentes); caso contrário, helpers de URL e redirects podem continuar apontando para a porta antiga.

Pré-requisitos reais de migrate e escopo dos testes

Na primeira execução, o Migrator tenta conectar sem selecionar um database e executar CREATE DATABASE IF NOT EXISTS. O usuário PDO precisa dos privilégios necessários para essa operação (e DROP/CREATE no modo --fresh). Como o Migrator executa CREATE DATABASE IF NOT EXISTS mesmo no fluxo normal, uma credencial sem privilégio de criação pode falhar antes das migrations; use credencial de provisionamento adequada ou ajuste explicitamente a estratégia/implementação de provisionamento.

php mvc migrate --fresh é destrutivo: a implementação derruba e recria o database inteiro, não apenas as tabelas da aplicação. Faça backup. A opção exige confirmação digitando o nome do banco; --yes pula a pergunta e, em APP_ENV=production, a execução também exige --force. --force não substitui backup.

composer test executa o PHPUnit configurado, mas a distribuição atual não contém casos de teste de unidade/feature (os diretórios são placeholders). Esse comando verifica o runner e as dependências, não comprova por si só o comportamento do framework. Adicione seus próprios testes em tests/Unit e tests/Feature.