Download the PHP package palacios/framework without Composer

Palacios Framework

Framework web MVC moderno para PHP 8.5, com roteamento declarativo, injeção de dependência, model binding, validação, middleware, autenticação, autorização, proteção antiforgery, views, banco de dados, migrations e ferramentas de linha de comando.

O código da aplicação fica separado do framework: o Composer instala o núcleo em vendor/palacios/framework, enquanto seu projeto mantém apenas as regras de negócio, controllers, models, repositories, services e views.

Requisitos

Antes de começar, instale:

• PHP 8.5 ou superior;
• Composer 2;
• extensões PHP json, mbstring, PDO e session;
• um driver PDO para o banco escolhido, como pdo_mysql ou pdo_sqlite.

Confirme o ambiente:

Criando seu primeiro projeto

Instale a ferramenta globalmente:

Crie e execute uma aplicação:

Acesse http://localhost:8000.

Se o comando framework não for encontrado, adicione o diretório global de binários do Composer ao PATH ou execute:

O comando new:

• copia a estrutura inicial da aplicação;
• cria o arquivo .env;
• gera automaticamente uma APP_KEY;
• configura a dependência da versão instalada;
• executa composer install.

Use --no-install quando quiser instalar as dependências depois:

Estrutura da aplicação

Principais diretórios:

• app/: código da sua aplicação;
• bootstrap/app.php: registro de serviços, middleware e rotas;
• database/migrations/: alterações versionadas do banco;
• public/: único diretório que deve ficar exposto pelo servidor web;
• resources/: arquivos de estilo e outros recursos;
• tests/: testes da aplicação;
• vendor/: dependências gerenciadas pelo Composer; não edite esse diretório.

Como uma requisição é processada

O arquivo public/index.php inicia a aplicação definida em bootstrap/app.php. O pipeline executa os middleware habilitados, encontra a rota correspondente, resolve as dependências do controller, converte os dados da requisição em parâmetros tipados e produz a resposta HTTP.

A ordem das chamadas use*() em bootstrap/app.php também é a ordem do pipeline.

Configuração inicial

O projeto gerado carrega as variáveis do arquivo .env e cria a aplicação:

O arquivo criado pelo comando new já contém uma configuração funcional. Habilite somente os middleware necessários ao projeto.

Criando um controller

Gere o arquivo:

Defina o prefixo e as ações com atributos:

addControllers() descobre as classes em app/Controllers e mapControllers() registra suas rotas.

Rotas diretas e grupos

Rotas também podem ser declaradas no bootstrap:

Agrupe endpoints que compartilham prefixo ou regras:

Rotas nomeadas permitem gerar URLs sem repetir caminhos:

Injeção de dependência

Registre contratos e implementações em bootstrap/app.php:

Tempos de vida disponíveis:

• addScoped: uma instância por requisição;
• addTransient: uma nova instância a cada resolução;
• addSingleton: uma única instância durante a aplicação.

Depois, solicite a dependência pelo construtor:

Interfaces, repositories e services podem ser usados sem DTOs. DTOs são opcionais e úteis quando você quer representar e validar dados de entrada de forma explícita.

Recebendo dados da requisição

Parâmetros tipados são preenchidos automaticamente por convenção a partir da rota, query string, formulário, JSON ou container:

Quando houver ambiguidade, indique a origem:

• #[FromRoute]: parâmetro da rota;
• #[FromQuery]: query string;
• #[FromForm]: formulário;
• #[FromBody]: corpo JSON;
• #[FromHeader]: cabeçalho HTTP;
• #[FromServices]: container de serviços.

Em código bem tipado e sem ambiguidade, esses atributos não são obrigatórios.

DTOs e validação

Um DTO pode centralizar os dados e suas regras:

Use DTOs quando eles deixarem a entrada mais clara. Para ações simples, parâmetros escalares tipados ou services injetados continuam válidos.

Views

Retorne uma view passando seus dados:

No arquivo app/Views/users/index.php:

O helper e() escapa conteúdo para HTML. Os layouts ficam, por padrão, em app/Views/layouts.

Se a view ou o layout lançar uma exceção, o framework descarta o HTML parcial e encaminha a exceção ao tratamento global. Os buffers existentes antes da renderização são preservados. Templates que criam buffers adicionais devem mantê-los removíveis (o padrão de ob_start()) e não fechar os buffers do renderizador.

Formulários e proteção antiforgery

Ative o middleware antes de mapear os controllers:

Inclua o campo oculto em formulários que alteram dados:

O framework valida automaticamente o token nas requisições protegidas. O campo interno _csrf não é incluído no model binding, portanto o controller recebe apenas os dados do formulário e não precisa remover o token manualmente.

O próprio helper obtém e reutiliza o token guardado na sessão. Não gere o token no controller nem o envie como dado da view. Se a geração criptograficamente segura falhar, o framework interrompe a operação e o tratamento global devolve 500; ele nunca renderiza um token vazio nem usa uma alternativa insegura.

Autenticação e autorização

Registre os serviços:

Adicione os middleware nesta ordem:

Proteja endpoints:

Controllers também podem usar #[Authorize]. Sem páginas de interface configuradas, acessos negados retornam 401 ou 403; com loginPath() e accessDeniedPath(), aplicações web recebem redirecionamentos.

Middleware

Crie um middleware:

Registre middleware globais no pipeline ou associe-os a grupos de rotas:

Use middleware para responsabilidades transversais, como logs, autenticação, autorização, antiforgery, cabeçalhos e tratamento de erros.

Logging de requisições

Ative o registro de requisições no bootstrap da aplicação:

Sem configuração adicional, o framework registra uma linha JSON no log de erros do PHP usando a categoria HTTP. Para usar outra implementação, registre-a antes de construir a aplicação:

A implementação personalizada deve implementar a interface Logger. O registro da aplicação sempre substitui o logger padrão do middleware.

O logging envolve todo o processamento HTTP, incluindo respostas 404 e 405. Cada requisição gera um único registro com método, caminho, status final, duração e traceId; chamadas repetidas a useRequestLogging() não duplicam o registro.

Banco de dados

Configure o .env:

Também é possível informar uma DSN completa:

Registre a conexão:

Repositories podem receber PDO diretamente pelo construtor.

Migrations

Gere uma migration:

Implemente as alterações:

Aplique as migrations pendentes:

O histórico das migrations executadas fica na tabela framework_migrations.

Geradores disponíveis

Os geradores usam namespaces PSR-4 e não sobrescrevem arquivos existentes. make:repository cria a interface e a implementação.

Resultados HTTP

Handlers e controllers podem retornar implementações de IActionResult:

Exceções HTTP são convertidas em respostas application/problem+json. Detalhes internos ficam visíveis somente no ambiente de desenvolvimento.

Executando com Docker

O projeto inicial inclui Dockerfile e docker-compose.yml:

Ajuste as variáveis do banco no .env conforme o ambiente utilizado.

Testes

Execute os testes da aplicação:

Para testes de integração, use WebApplicationFactory:

Ambientes

Defina o ambiente no .env:

Valores comuns:

• Development: página detalhada de exceções;
• Production: respostas seguras sem detalhes internos.

Nunca habilite a página detalhada de exceções em produção.

Servidor web em produção

Configure Apache, Nginx ou outro servidor para usar public/ como document root. Não exponha a raiz do projeto, o arquivo .env, vendor/ ou app/ diretamente pela web.

O servidor embutido do PHP é indicado apenas para desenvolvimento local:

Atualizando o framework

Verifique versões disponíveis:

Atualize dentro da restrição permitida pelo projeto:

Leia o changelog antes de atualizar entre versões menores enquanto o projeto estiver na série 0.x.

Ajuda e segurança

• Consulte o CHANGELOG para alterações por versão.
• Consulte a política de segurança para reportar vulnerabilidades.
• O projeto é distribuído sob a licença MIT.

A série 0.x representa a fase inicial da API. Mudanças incompatíveis podem ocorrer em versões menores até a estabilização da versão 1.0.0.