---
title: "Para desenvolvedores"
description: "O guia do desenvolvedor: arquitetura sem banco de dados, testes, pacote de distribuição, personalização do tema do Éclair CMS, Nginx e contribuição."
url: "https://eclaircms.org/pt/documentacao/desenvolvedores"
lang: "pt"
author: "Thierry Gustin"
published: "2026-10-30"
updated: "2026-11-01"
---

# Para desenvolvedores

> **O essencial** — O Éclair é escrito em PHP 8.1+ sem framework nem Composer: um controlador frontal que serve o cache estático, um armazenamento em arquivos protegidos, classes simples e JavaScript nativo. O tema do Éclair CMS se personaliza em app/theme; 550 verificações automáticas e uma ferramenta de build acompanham o código, sob licença MIT.

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 479 KB, nenhuma dependência e páginas servidas em 0,7 ms nas nossas medições locais.

## O que há na pasta eclair?

```text
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:

```bash
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](https://eclaircms.org/pt/instalacao/local).

## Como rodar os testes?

```bash
php tests/run.php          # 550 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?

```bash
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/`:

| Arquivo | Função |
| --- | --- |
| `layout.php` | Template principal: cabeçalho, menu, rodapé |
| `single.php` | Uma página ou um artigo |
| `list.php` | Blog, categorias, páginas de autor e pesquisa |
| `cards.php` | A grade de cards de artigos |
| `404.php` | A página não encontrada |
| `theme.css` | Os estilos, minificados e depois inseridos em cada página |

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.

> **Respeite a política de segurança** — A Content-Security-Policy do site público proíbe scripts embutidos: coloque seu JavaScript em um arquivo de `assets/`. Quanto aos estilos, só a tag `<style>` do tema é permitida, graças ao hash SHA-256 dela, calculado automaticamente; os atributos `style=""` são bloqueados.

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](https://eclaircms.org/pt/documentacao/atualizacoes)). 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:

```nginx
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`, `session` e `zlib` são indispensáveis. `gd` (imagens WebP), `zip` (backups), `curl` (IndexNow e assistente de IA) 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](https://github.com/Jacckisback/eclair-cms): 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](https://lucide.dev), sob a licença ISC. Você também pode apoiar o projeto na página [Doar](https://eclaircms.org/pt/doar).

## Perguntas dos desenvolvedores

### Preciso do Composer ou do Node.js para desenvolver no Éclair?

Não. O Éclair não tem nenhuma dependência: o PHP 8.1 ou superior basta para rodar o site, os testes e a ferramenta de build.

### Posso criar o meu próprio tema do Éclair CMS?

Pode: edite os templates de app/theme e o arquivo theme.css. Respeite a política de segurança (nenhum script embutido) e guarde uma cópia dos seus arquivos, que uma atualização substituiria.

### Onde ficam armazenados os conteúdos?

Em data/content, um arquivo por conteúdo, em formato JSON precedido da linha de proteção. O data/index.php guarda um resumo deles para listar e rotear rápido.

### Como adicionar uma tradução da administração?

As fontes legíveis estão na pasta i18n do repositório, com o texto em francês servindo de chave. O tools/i18n.php as compila em arquivos compactados, e o php tools/build.php faz isso automaticamente.