Referência do Velk

Começando

Requisitos

• PHP 8.2 ou superior
• MySQL 5.7+ ou MariaDB 10.2+ (o Velk usa colunas JSON nativas)
• Apache com .htaccess (incluso) — no nginx, escreva a regra de rewrite à mão

Instalação com IA (recomendada)

No fluxo de vibe coding você não baixa nada: a skill oficial cuida disso. Instale-a no Claude Code e peça a instalação — a IA baixa a release oficial, verifica o checksum, configura o .env e roda o instalador. O passo a passo está em Como usar.

Instalação manual (sem IA)

Pra quem prefere programar direto: o Velk é distribuído como tarball versionado — não é um clone de repositório. Baixe a release, extraia na pasta do projeto, preencha o .env a partir do .env.example (banco e usuário admin inicial) e rode o instalador:

Baixar a última versão

Variáveis principais do .env: DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, INITIAL_USER_EMAIL, INITIAL_USER_PASSWORD, INITIAL_USER_NAME e APP_URL (opcional em local — usado pelo sitemap e por absolute_url()). SMTP é opcional: sem SMTP_HOST/USER/PASS/FROM, formulários salvam mas não enviam e-mail.

Estrutura de pastas

core/           engine — nunca edite
bin/velk        CLI
migrations/     engine — aplicadas no install/upgrade
theme/          o SEU site: site.json, templates, assets
storage/        uploads e arquivos gerados
.env            credenciais
.velk-version   versão instalada (usada pelo upgrade)

site.json

theme/site.json é a fonte da verdade da estrutura: o painel administrativo é gerado dele. Chaves de topo:

Templates são vinculados por nome de arquivo, nunca por slug — renomeie slugs à vontade sem quebrar bindings. Depois de qualquer edição, rode ./bin/velk schema:validate.

Tipos de campo

Comuns a qualquer campo: name (obrigatório), label, help, required, placeholder. field('name') devolve o valor bruto — escalar nos simples, array em gallery/repeater/flexible.

Templates

Ordem de resolução:

1. Página estrutural: template → fallback page.php
2. Página criada no admin: file do template escolhido → page.php
3. Item: template próprio do item (se houver) → template do tipo → single.php
4. Arquivo de itens: archive_template → archive.php
5. Arquivo de taxonomia: template da taxonomia → taxonomy.php

<?php with_context($item, function () {
    get_header(); ?>

    <article class="post">
        <h1><?= e(the_title()) ?></h1>
        <?= field('content') /* trusted */ ?>
    </article>

<?php get_footer(); }); ?>

with_context() deixa field(), the_title() e afins funcionarem sem passar o registro adiante. Cada tipo de template recebe uma variável de contexto:

Helpers

Todos globais nos templates (definidos em core/helpers.php).

Saída e contexto

Conteúdo

URLs e mídia

Layout e diversos

URLs & rotas

• / → página home
• /{page-key} → demais páginas estruturais (ou a URL explícita declarada)
• /{type-slug} → arquivo · /{type-slug}/{item-slug} → item
• /{taxonomy-slug}/{term-slug} → arquivo do termo
• /admin → painel · /uploads/... → mídia · /theme/... → assets estáticos do tema (sem PHP)

O base path é detectado sozinho de SCRIPT_NAME, então o site funciona instalado na raiz ou em sub-diretório (site.com/velk/) sem configurar nada — desde que o tema use sempre os helpers de URL. Se um host exótico errar a detecção: 'base_path' => '/velk' em config/env.php.

Mídia

Biblioteca em /admin/media: upload (jpeg, png, gif, webp, svg, pdf — até 25 MB), texto alternativo, copiar URL e exclusão com limpeza dos tamanhos gerados. Nomes de arquivo são slugificados; colisões ganham sufixo -1, -2…

storage/uploads/{file}.{ext}          originais
storage/uploads/thumb/{file}.{ext}    gerado sob demanda (GD)
storage/uploads/hero/{file}.{ext}     gerado sob demanda (GD)

Os tamanhos vêm de image_sizes no site.json — crop: true corta exato, false encaixa proporcional. No tema: image_url(field('photo'), 'thumb').

Opções globais

"options": {
  "contact": {
    "label": "Contact",
    "fields": [
      { "name": "phone", "type": "text", "label": "Phone" }
    ]
  }
}

Cada entrada vira um link na sidebar do admin e um formulário só de campos. Leia com option('contact.phone') — o dot path entra em grupos e linhas de repeater (option('contact.social.0.url')). Tudo de uma página sai com options('contact'). Armazenado como uma linha JSON em settings, com cache em processo: 50 chamadas, uma query.

Formulários

"forms": {
  "contact": {
    "label": "Contact",
    "subject": "New contact: {{name}}",
    "success_message": "Message sent.",
    "fields": [
      { "name": "name", "type": "text", "label": "Name", "required": true }
    ]
  }
}

Tipos aceitos: text, email, tel, url, number, textarea, checkbox, hidden, select (com required e maxlength). O assunto aceita placeholders {{field}} preenchidos com a submissão.

O tema escreve o HTML do formulário:

• form_url('contact') no action (POST)
• csrf_field() + form_honeypot() dentro do form
• form_status('contact') pra ler o flash — status, mensagem, valores e erros

Ciclo: valida CSRF + honeypot + campos, salva em form_submissions, envia o e-mail aos destinatários definidos em /admin/forms/contact e redireciona de volta. E-mail que falha não perde a submissão.

Membros

Contas do site público — tabelas, autenticação e sessões separadas dos usuários do admin. Sem papéis pré-definidos: cada site declara os seus tipos e o tema decide o que cada um acessa.

"members": {
  "enabled": true,
  "types": {
    "client": { "label": "Client",
      "fields": [ { "name": "company", "type": "text" } ] }
  },
  "routes": { "login": "/login" }
}

Registro público vem desligado (public_registration: false) — por padrão só o admin cria contas. O tema constrói os formulários de login/registro/reset contra os endpoints POST do engine, sempre com csrf_field().

Multi-idioma

Três camadas independentes, todas nativas:

• Strings fixas do tema — embrulhe em t('Leia mais'); catálogo gerado por i18n:scan e traduzido em /admin/translations.
• URLs estruturais — slugs de páginas, tipos e taxonomias por idioma: /blog/post-x vira /en/news/post-x.
• Conteúdo por registro — título, slug e campos com colunas *_translations e abas por idioma no próprio editor.

"i18n": { "enabled": true, "default": "en" }

Os demais idiomas são cadastrados em /admin/languages, cada um com prefixo de URL. Nos templates, nada muda: field(), the_title() e option() já resolvem o idioma ativo com fallback pro padrão — escreva o template uma vez.

URLs de idioma não-padrão são estritas — sem slug traduzido, sem URL naquele idioma (nada de conteúdo duplicado pro Google). O sitemap emite os hreflang só quando a tradução existe de verdade.

CLI

./bin/velk <comando>, da raiz do projeto. Quase tudo que o painel faz, a CLI faz — é o que deixa a IA operar o site.

Setup e schema

Conteúdo

Flags úteis

• --format=json — saída legível por máquina
• --dry-run — valida sem salvar
• --json-stdin — payload via stdin, sem inferno de aspas no shell

Deploy & upgrades

Deploy

• Hospedagem compartilhada sem SSH: suba os arquivos por FTP/painel — o auto-migrate completa a instalação no primeiro acesso.
• Com SSH (VPS, cloud, cPanel com terminal): a skill oficial cobre o fluxo completo — arquivos, banco, storage e robots.txt com a URL de produção.
• Sub-diretório: funciona sem configuração, porque os helpers de URL prefixam o base path sozinhos.

Em produção, preencha APP_URL no .env — o sitemap e o absolute_url() dependem dele.

Upgrades

O engine é uma dependência versionada, distribuída por tarball com checksum. O upgrade lê a versão em .velk-version, baixa a nova, verifica o sha256 e substitui apenas os caminhos do engine — theme/, storage/, .env, .htaccess e robots.txt ficam como estão. Peça pra IA: "atualiza o Velk desse projeto".