Para desenvolvedores

O Éclair é escrito em PHP 8.1 ou superior, sem framework e sem Composer: classes simples em app/lib/, views em PHP e JavaScript nativo. Este guia explica a arquitetura dele, como rodar os testes e preparar um pacote de distribuição, como personalizar o tema do Éclair CMS sem comprometer a segurança e como servi-lo com o Nginx.

Como o Éclair é construído?

Três ideias o tornam leve e rápido:

1. Um controlador frontal que serve o cache sem carregar a aplicação. O index.php procura primeiro a página pedida em cache/pages/ e a envia diretamente, com seus cabeçalhos e seu ETag (resposta 304 se nada mudou). A aplicação só é carregada para uma página que ainda não está em cache, para a administração ou para a instalação.
2. Um armazenamento em arquivos, sem banco de dados. Cada dado é um arquivo .php que começa com <?php exit; ?>, seguido de JSON. As gravações são atômicas (arquivo temporário e depois renomeação), privadas (0600) e feitas sob bloqueio exclusivo nas operações de leitura-modificação-gravação. O data/index.php guarda um resumo de todos os conteúdos para listar e rotear rápido.
3. Blocos validados e depois renderizados. Cada bloco é validado e higienizado por lista de permissões, depois renderizado em HTML, exportado em Markdown para o GEO e analisado para o SEO.

Resultado: um arquivo de 440 KB, nenhuma dependência e páginas servidas em 0,7 ms nas nossas medições locais.

O que há na pasta eclair?

eclair/                  ← o que vai para a hospedagem
├── index.php            controlador frontal (serve o cache sem carregar a aplicação)
├── .htaccess            reescrita, proteções, compressão, cache do navegador
├── app/lib/             código (classes Eclair\…): Content, Blocks, Seo, Analyzer, Media, Auth…
├── app/admin/views/     telas da administração
├── app/theme/           templates do site público + theme.css (inserido em cada página)
├── app/lang/            traduções da administração (6 idiomas, JSON compactado)
├── assets/admin/        CSS e JavaScript da administração (sem dependências)
├── assets/site/site.js  o único script público (2,4 KB, 1,2 KB compactado)
├── data/                conteúdos, configurações, contas (criado na instalação, nunca público)
├── cache/               páginas geradas
└── media/               imagens enviadas

No repositório, i18n/ contém as fontes legíveis das traduções, tests/ os testes e tools/ o roteador de desenvolvimento e a ferramenta de build.

Como rodar o Éclair localmente?

A partir do repositório, o servidor embutido do PHP basta:

PHP_CLI_SERVER_WORKERS=4 php -S localhost:8000 -t eclair tools/router.php

O tools/router.php reproduz as regras do .htaccess. O PHP_CLI_SERVER_WORKERS permite que o site chame a si mesmo para verificar o próprio endereço: com um único processo, a verificação simplesmente falha e os redirecionamentos para o endereço oficial continuam desativados. Para um teste sem linha de comando, veja Testar o Éclair no seu computador.

Como rodar os testes?

php tests/run.php          # 502 verificações unitárias e HTTP
php tests/run.php --unit   # somente testes unitários

Os testes de integração iniciam um servidor PHP de verdade e reproduzem boa parte dos ataques da revisão de segurança. O tests/fake-ai.php simula os provedores de IA (Claude, ChatGPT, imagens): o assistente é testado sem chave e sem gasto.

Como preparar um pacote de distribuição?

php tools/build.php

A ferramenta recompila as traduções a partir de i18n/, calcula a impressão digital SHA-256 de cada arquivo em app/manifest.php, a referência da verificação de integridade, e depois cria dist/eclair-cms-<versão>.zip com o arquivo LISEZ-MOI (“leia-me”, em francês), a licença e os avisos de terceiros.

Como personalizar o tema do Éclair CMS?

O site público é renderizado pelos templates de app/theme/:

As configurações de aparência viram variáveis CSS que o seu tema pode reutilizar: --accent, --on-accent, --link, --link-dark, --font e --font-head. O modo escuro fica entre os comentários /*dark*/ e /*/dark*/: o Éclair remove esse bloco quando a opção “Sempre claro” é escolhida.

Guarde uma cópia dos seus templates: a verificação de integridade vai apontá-los como modificados, o que é normal, e uma atualização do Éclair os substitui (veja Atualizar). O site eclaircms.org que você está lendo foi construído com o próprio Éclair e um tema personalizado: menu fixo, documentação com menu lateral, páginas anterior e seguinte.

Como servir o Éclair com o Nginx?

O Éclair não precisa de .htaccess no Nginx, mas é preciso reproduzir estas regras:

location ~ ^/(app|data|cache)(/|$) { return 404; }
location ~ /\.(?!well-known/) { return 404; }
location ^~ /media/ {
    location ~* \.(php\d?|phtml|phar|s?html?|svgz?|xml|js)$ { return 404; }
    add_header X-Content-Type-Options nosniff;
    expires 1y;
}
location ~* \.(webp|avif|jpe?g|png|gif|ico|css|js|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; }
location / { try_files $uri /index.php$is_args$args; }
location = /index.php {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    fastcgi_pass unix:/run/php/php-fpm.sock;
}
location ~ \.php$ { return 404; }

Para que as respostas do assistente de IA apareçam aos poucos, adicione fastcgi_buffering off; no bloco do PHP.

Quais versões do PHP e quais extensões são necessárias?

O Éclair funciona do PHP 8.1 ao 8.5; o 8.3 é recomendado. As extensões mbstring, json, dom e session são indispensáveis. gd (imagens WebP), zip (backups), curl (IndexNow e assistente de IA), zlib (administração traduzida) e sodium ou openssl (chaves do assistente) são recomendadas. O assistente de instalação verifica tudo isso.

Como contribuir com o Éclair?

O código é público no GitHub: relate um bug ou proponha uma ideia nas issues, ou envie um pull request acompanhado de testes. O Éclair é distribuído sob a licença MIT; parte dos ícones da administração deriva do Lucide, sob a licença ISC. Você também pode apoiar o projeto na página Doar.