README

Write what matters.

SparkPHP e um framework PHP file-based, zero-config e observavel por default. Ele existe para reduzir wiring, cortar boilerplate e deixar o comportamento da aplicacao visivel no CLI, no Inspector e na propria estrutura de arquivos.

Versao publicada atual: 0.10.0 (0.10.x).

Dois arquivos. Sem controller. Sem service provider. Sem registro.

// app/routes/users.php
get(fn() => ['users' => User::all()]);

{{-- app/views/users.spark --}}
@title('Usuarios')

@foreach($users as $user)
  <p>{{ $user->name }}</p>
@endforeach

Isso e suficiente para:

• GET /users com browser → HTML com layout automatico
• GET /users com Accept: application/json → JSON sem alterar uma linha
• php spark routes:list → lista a rota no CLI
• /_spark → mostra o request completo no Inspector

O que o Spark otimiza

• Menos wiring: nenhum arquivo de registro, nenhum service provider, nenhum Kernel.
• Mais previsivel: o arquivo e a convencao dizem o que acontece.
• Mais observavel: request, cache, queries, AI e benchmark fazem parte do produto.

Nucleo do Spark

O runtime base carrega apenas o que e necessario para cada request:

• Router · Request/Response · Middleware · Container
• Template Engine · Database · Model · Validator
• Session · Cache · Logger · Helpers · CLI

O que e core obrigatorio, o que e first-party opcional e o que e experimental:

• Fronteira do produto

SparkPHP vs Laravel

O Spark nao tenta ganhar do Laravel por “ter mais coisas”.

Ele tenta ser melhor em outro eixo:

• menos wiring para o caso comum
• menos superficie para lembrar
• mais visibilidade operacional sem setup extra

Quando o problema pede ecossistema enorme, pacotes first-party maduros e ampla disponibilidade de time, o Laravel continua excelente.

Quando o problema pede previsibilidade, baixo atrito e um framework que cabe na cabeca do time, o Spark entra muito forte.

Guia honesto de comparacao:

• SparkPHP vs Laravel
• Guia de Adoção
• Benchmarks
• Migração a partir do Laravel
• Review Checklist

Quick Start

composer install
php spark init
php spark serve

Ou gere um projeto novo ja com um starter first-party:

php spark starter:list
php spark new ../meu-saas --starter=saas

Starter kits

O runtime atual publica quatro presets oficiais:

• api
• saas
• admin
• docs

Todos continuam sendo Spark puro: rotas em arquivo, templates .spark, CLI versionada, docs em Markdown e observabilidade nativa.

Guia completo:

• Starter Kits

Documentacao

O indice principal da documentacao fica em:

• docs/README.md

Topicos principais:

• Instalacao
• Routing
• Request & Response
• Database
• CLI
• AI SDK

Benchmarks e observabilidade

O Spark publica benchmark e diagnostico como partes do produto:

php spark about
php spark benchmark
php spark inspector:status

O objetivo nao e vender microbenchmark isolado. O objetivo e medir ciclo HTTP, DX e operacao de forma repetivel.

Maturidade por subsistema

• Categoria — onde o subsistema pertence na fronteira do produto
• Maturidade — garantia de estabilidade da API publica:
  • Estavel: contrato fixo; breaking changes apenas em major
  • Beta: adequado para producao; API pode mudar em minors com upgrade guide
  • Experimental: nao usar em producao sem avaliacao; pode mudar sem aviso

Politica completa: Releases & Compatibilidade · Fronteira do produto

Estado do projeto

O SparkPHP esta na linha 0.x, ainda consolidando contrato publico. Isso significa:

• a linha ja busca previsibilidade real
• minors ainda podem trazer mudancas estruturais documentadas
• toda release relevante deve atualizar VERSION, CHANGELOG.md e os guias de upgrade

Mais detalhes:

• Releases & Compatibilidade
• Upgrade Guide
• Contributing