README

Micro-framework PHP puro, construído do zero, focado em performance, segurança e arquitetura moderna. Ideal para aprender como um framework funciona por dentro ou como base para aplicações reais.

Por que este framework?

A maioria dos tutoriais de PHP ensina a usar o Laravel e esconde toda a mágica por baixo. Este projeto foi construído para revelar essa mágica — cada classe representa um conceito real de arquitetura:

• O Router implementa pattern matching com regex e pipeline de middlewares
• O Container faz autowiring via PHP Reflection API (como o Laravel)
• O Model implementa o padrão Active Record com Eager Loading N+1-safe
• O Kernel segue o padrão PSR-15 de pipeline de requisição

Features Principais

Instalação

Método 1: Via Composer (Recomendado)

composer create-project felipe-code/mvc-base nome-do-seu-projeto

O instalador interativo irá configurar o .env e preparar o projeto automaticamente.

Método 2: Via Git Clone

git clone https://github.com/FelipeOropeza/mvc-estrutura.git meu-app
cd meu-app
composer install
composer run post-create-project-cmd

Método 3: Via Docker (FrankenPHP + Mercure)

docker-compose up -d --build

Acesse http://localhost:8000. O FrankenPHP roda em Worker Mode para máxima performance (milissegundos por requisição).

Início Rápido (Servidor Local)

# Inicia o servidor embutido do PHP apontando para /public
composer start

Acesse http://localhost:8000.

CLI — Forge

A ferramenta de linha de comando para scaffolding e manutenção:

# Criação de código
php forge make:controller NomeController
php forge make:controller Api/UserController --api
php forge make:model ProdutoModel
php forge make:view secao/minha-view
php forge make:component meu-componente
php forge make:migration CreateProdutosTable
php forge make:middleware VerificarAcessoMiddleware
php forge make:rule CpfValido
php forge make:mutator LimpaCpf

# Banco de dados
php forge migrate
php forge migrate:rollback
php forge migrate:fresh

# Scaffolding de sistemas completos
php forge setup:auth       # Sistema de autenticação completo
php forge setup:api        # Scaffold de API JWT
php forge setup:aviso      # Demo de avisos em tempo real (Mercure)

# Processamento de filas
php forge queue:work

# Otimização de produção
php forge optimize         # Cache de rotas para performance máxima
php forge optimize:clear   # Limpa o cache de rotas

Estrutura de Diretórios

.
├── app/
│   ├── Controllers/     # Lógica HTTP
│   ├── Models/          # Active Record (estende Core\Database\Model)
│   ├── Middleware/      # Middlewares da aplicação
│   └── Providers/       # Service Providers
├── bootstrap/           # Inicialização do framework
├── config/              # Configurações (app, database, middleware, mail...)
├── core/                # O framework em si
│   ├── Auth/            # TokenManager (JWT)
│   ├── Cache/           # Drivers de cache (File, Redis)
│   ├── Database/        # Connection (PDO), Model, QueryBuilder
│   ├── Exceptions/      # Handler, HttpException, ValidationException
│   ├── Http/            # Request, Response, Kernel, Pipeline, Session
│   ├── Mail/            # MailManager, PHPMailer driver
│   ├── Queue/           # QueueManager, Job
│   ├── Routing/         # Router, AttributeRouteScanner, RouteCompiler
│   ├── Support/         # Container (IoC), Logger, helpers.php
│   ├── Validation/      # Validator, DataTransferObject
│   └── View/            # PhpEngine, EngineInterface
├── database/
│   └── migrations/      # Arquivos de migração
├── docs/                # Documentação completa
├── public/              # Document root (index.php, assets)
├── resources/views/     # Templates PHP
├── routes/              # web.php, api.php
├── storage/             # Logs, cache, sessões, uploads
├── forge                # CLI entry point (Linux/Mac)
└── forge.bat            # CLI entry point (Windows)

Exemplo Rápido

Rota + Controller + Model em 3 arquivos:

// routes/web.php
Route::get('/produtos', [ProdutoController::class, 'index'])->name('produtos.index');
Route::post('/produtos', [ProdutoController::class, 'store']);

// app/Controllers/ProdutoController.php
class ProdutoController extends Controller
{
    public function index(): Response
    {
        $produtos = (new Produto())->orderBy('nome')->get();
        return view('produtos/index', compact('produtos'));
    }

    public function store(): Response
    {
        $data = validate(new ProdutoDto());
        (new Produto())->insert($data);
        return redirect(route('produtos.index'));
    }
}

// app/Models/Produto.php
class Produto extends Model
{
    protected array $fillable = ['nome', 'preco', 'categoria_id'];
    protected array $hidden   = ['custo_interno'];

    public function categoria(): ?Categoria
    {
        return $this->belongsTo(Categoria::class, 'categoria_id');
    }
}

Documentação Completa

Consulte a pasta docs/ para guias detalhados:

➡ Índice da Documentação

Exemplos em Destaque

• Avisos em Tempo Real — Notificações instantâneas com HTMX e Mercure em menos de 5 minutos.

Requisitos

• PHP 8.1+ (recomendado 8.3+)
• Extensões: pdo, pdo_mysql (ou pdo_pgsql / pdo_sqlite), mbstring, openssl
• Composer 2.x

Licença

MIT — Feito com propósito educacional e uso em produção.