Referencia de Velk

Empezando

Requisitos

• PHP 8.2 o superior
• MySQL 5.7+ o MariaDB 10.2+ (Velk usa columnas JSON nativas)
• Apache con .htaccess (incluido) — en nginx, escribe la regla de rewrite a mano

Instalación con IA (recomendada)

En el flujo de vibe coding no descargas nada: la skill oficial se encarga. Instálala en Claude Code y pide la instalación — la IA descarga la release oficial, verifica el checksum, configura el .env y ejecuta el instalador. El paso a paso está en Cómo usar.

Instalación manual (sin IA)

Para quien prefiere programar directo: Velk se distribuye como un tarball versionado — no es un clon de repositorio. Descarga la release, extráela en la carpeta del proyecto, rellena el .env a partir del .env.example (base de datos y usuario admin inicial) y ejecuta el instalador:

Descargar la última versión

Variables principales del .env: DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, INITIAL_USER_EMAIL, INITIAL_USER_PASSWORD, INITIAL_USER_NAME y APP_URL (opcional en local — usada por el sitemap y por absolute_url()). SMTP es opcional: sin SMTP_HOST/USER/PASS/FROM, los formularios guardan pero no envían email.

Estructura de carpetas

core/           engine — nunca editar
bin/velk        CLI
migrations/     engine — aplicadas en la instalación/actualización
theme/          TU sitio: site.json, plantillas, assets
storage/        uploads y archivos generados
.env            credenciales
.velk-version   versión instalada (usada por el upgrade)

site.json

theme/site.json es la fuente de la verdad de la estructura: el panel administrativo se genera de él. Claves de nivel superior:

Las plantillas se vinculan por nombre de archivo, nunca por slug — renombra slugs a voluntad sin romper los bindings. Tras cualquier edición, ejecuta ./bin/velk schema:validate.

Tipos de campo

Comunes a cualquier campo: name (obligatorio), label, help, required, placeholder. field('name') devuelve el valor crudo — escalar en los simples, array en gallery/repeater/flexible.

Plantillas

Orden de resolución:

1. Página estructural: template → fallback page.php
2. Página creada en el admin: file de la plantilla elegida → page.php
3. Item: la plantilla propia del item (si hay) → la plantilla del tipo → single.php
4. Archivo de items: archive_template → archive.php
5. Archivo de taxonomía: la plantilla de la taxonomía → 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() permite que field(), the_title() y compañía funcionen sin pasar el registro alrededor. Cada tipo de plantilla recibe una variable de contexto:

Helpers

Todos globales en las plantillas (definidos en core/helpers.php).

Salida y contexto

Contenido

URLs y medios

Layout y varios

URLs y rutas

• / → página de inicio
• /{page-key} → demás páginas estructurales (o la URL explícita declarada)
• /{type-slug} → archivo · /{type-slug}/{item-slug} → item
• /{taxonomy-slug}/{term-slug} → archivo del término
• /admin → panel · /uploads/... → medios · /theme/... → assets estáticos del tema (sin PHP)

El base path se detecta solo desde SCRIPT_NAME, así que el sitio funciona instalado en la raíz o en un subdirectorio (site.com/velk/) sin configurar nada — siempre que el tema use siempre los helpers de URL. Si un host exótico falla la detección: 'base_path' => '/velk' en config/env.php.

Medios

Biblioteca en /admin/media: subida (jpeg, png, gif, webp, svg, pdf — hasta 25 MB), texto alternativo, copiar URL y borrado que limpia los tamaños generados. Los nombres de archivo se slugifican; las colisiones reciben sufijo -1, -2…

storage/uploads/{file}.{ext}          originales
storage/uploads/thumb/{file}.{ext}    generado bajo demanda (GD)
storage/uploads/hero/{file}.{ext}     generado bajo demanda (GD)

Los tamaños vienen de image_sizes en el site.json — crop: true recorta exacto, false encaja proporcional. En el tema: image_url(field('photo'), 'thumb').

Opciones globales

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

Cada entrada se convierte en un enlace en la barra lateral del admin y en un formulario solo de campos. Léelo con option('contact.phone') — el dot path entra en grupos y filas de repeater (option('contact.social.0.url')). Toda una página sale con options('contact'). Almacenado como una fila JSON en settings, con caché en proceso: 50 llamadas, una query.

Formularios

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

Tipos aceptados: text, email, tel, url, number, textarea, checkbox, hidden, select (con required y maxlength). El asunto acepta placeholders {{field}} rellenados con el envío.

El tema escribe el HTML del formulario:

• form_url('contact') en el action (POST)
• csrf_field() + form_honeypot() dentro del form
• form_status('contact') para leer el flash — status, mensaje, valores y errores

Ciclo: valida CSRF + honeypot + campos, guarda en form_submissions, envía el email a los destinatarios definidos en /admin/forms/contact y redirige de vuelta. Un email fallido no pierde el envío.

Miembros

Cuentas del sitio público — tablas, autenticación y sesiones separadas de los usuarios del admin. Sin roles predefinidos: cada sitio declara sus tipos y el tema decide a qué accede cada uno.

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

El registro público viene desactivado (public_registration: false) — por defecto solo el admin crea cuentas. El tema construye los formularios de login/registro/reset contra los endpoints POST del engine, siempre con csrf_field().

Multi-idioma

Tres capas independientes, todas nativas:

• Cadenas fijas del tema — envuelve en t('Leer más'); catálogo generado por i18n:scan y traducido en /admin/translations.
• URLs estructurales — slugs de páginas, tipos y taxonomías por idioma: /blog/post-x se convierte en /en/news/post-x.
• Contenido por registro — título, slug y campos con columnas *_translations y pestañas por idioma en el propio editor.

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

Los demás idiomas se registran en /admin/languages, cada uno con prefijo de URL. En las plantillas nada cambia: field(), the_title() y option() ya resuelven el idioma activo con fallback al predeterminado — escribe la plantilla una vez.

Las URLs de idioma no predeterminado son estrictas — sin slug traducido, sin URL en ese idioma (nada de contenido duplicado para Google). El sitemap emite los hreflang solo cuando la traducción existe de verdad.

CLI

./bin/velk <comando>, desde la raíz del proyecto. Casi todo lo que hace el panel, lo hace la CLI — es lo que permite que la IA opere el sitio.

Setup y esquema

Contenido

Flags útiles

• --format=json — salida legible por máquina
• --dry-run — valida sin guardar
• --json-stdin — payload por stdin, sin infierno de comillas en el shell

Deploy y upgrades

Deploy

• Hosting compartido sin SSH: sube los archivos por FTP/panel — el auto-migrate completa la instalación en la primera petición.
• Con SSH (VPS, cloud, cPanel con terminal): la skill oficial cubre el flujo completo — archivos, base de datos, storage y robots.txt con la URL de producción.
• Subdirectorio: funciona sin configuración, porque los helpers de URL prefijan el base path solos.

En producción, rellena APP_URL en el .env — el sitemap y absolute_url() dependen de él.

Upgrades

El engine es una dependencia versionada, distribuida como tarball con checksum. El upgrade lee la versión en .velk-version, descarga la nueva, verifica el sha256 y reemplaza solo las rutas del engine — theme/, storage/, .env, .htaccess y robots.txt quedan como están. Pídele a la IA: "actualiza Velk en este proyecto".