Velk reference

Requirements

• PHP 8.2 or higher
• MySQL 5.7+ or MariaDB 10.2+ (Velk uses native JSON columns)
• Apache with .htaccess (included). On nginx, write the rewrite rule by hand

Install with AI (recommended)

In the vibe coding flow you download nothing: the official skill handles it. Install it in Claude Code and ask for the install — the AI downloads the official release, verifies the checksum, configures the .env and runs the installer. The step-by-step is in .env and runs the installer. The step-by-step is in How to use.

Manual install (without AI)

For those who prefer to code directly: Velk ships as a versioned tarball — not a repository clone. Download the release, extract it into the project folder, fill in the .env a partir do .env.example (database and initial admin user) and run the installer:

Main variables of the .env: DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, INITIAL_USER_EMAIL, INITIAL_USER_PASSWORD, INITIAL_USER_NAME and APP_URL (optional locally, used by the sitemap and by absolute_url()). SMTP is optional: without SMTP_HOST/USER/PASS/FROM, forms still save but send no email.

Folder structure

core/           engine, never edit
bin/velk        CLI
migrations/     engine, applied on install/upgrade
theme/          YOUR site: site.json, templates, assets
storage/        uploads and generated files
.env            credentials
.velk-version   installed version (used by the upgrade)

theme/site.json theme/site.json is the source of truth for structure: the admin panel is generated from it. Top-level keys:

Templates are bound by file name, never by slug — rename slugs freely without breaking bindings. After any edit, run ./bin/velk schema:validate. ./bin/velk schema:validate.

Common to every field: name (required), label, help, required, placeholder. field('name') returns the raw value: a scalar for simple fields, an array for gallery/repeater/flexible.

Resolution order:

1. Structural page: template → fallback page.php page.php
2. Admin-created page: file of the chosen template → page.php page.php
3. Item: the item's own template (if any) → the type's template → single.php single.php
4. Item archive: archive_template → archive.php archive.php
5. Taxonomy archive: the taxonomy's template → taxonomy.php 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() with_context() lets field(), the_title() and friends work without passing the record around. Each template type gets one context variable:

All global in templates (defined in core/helpers.php). core/helpers.php).

Output and context

Content

URLs and media

Layout and misc

• / → home page
• /{page-key} /{page-key} → other structural pages (or the explicit URL declared)
• /{type-slug} → archive · /{type-slug}/{item-slug} → item
• /{taxonomy-slug}/{term-slug} → term archive
• /admin → panel · /uploads/... → media · /theme/... → static theme assets (no PHP)

The base path is auto-detected from SCRIPT_NAME, so the site works installed at the root or in a subdirectory (site.com/velk/) with no configuration — as long as the theme always uses the URL helpers. If an exotic host gets detection wrong: 'base_path' => '/velk' in config/env.php. 'base_path' => '/velk' em config/env.php.

Biblioteca em /admin/mediaLibrary at /admin/media: upload (jpeg, png, gif, webp, svg, pdf — up to 25 MB), alt text, copy URL and deletion that cleans up generated sizes. File names are slugified; collisions get a -1, -2… suffix.

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

The sizes come from image_sizes in site.json: crop: true cuts exactly, false fits proportionally. In the theme: image_url(field('photo'), 'thumb').

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

Each entry becomes a sidebar link in the admin and a fields-only form. Read it with option('contact.phone'): the dot path reaches into groups and repeater rows (option('contact.social.0.url')). Everything from one page comes out with options('contact'). Stored as a single JSON row in settings, cached in-process: 50 calls, one query.

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

Accepted types: text, email, tel, url, number, textarea, checkbox, hidden, select (with required and maxlength). The subject accepts {{field}} placeholders filled from the submission. {{field}} filled in with the submission.

The theme writes the form HTML:

• form_url('contact') no action (POST)
• csrf_field() + form_honeypot() inside the form
• form_status('contact') to read the flash: status, message, values and errors

The cycle: validates CSRF + honeypot + fields, saves to form_submissions, emails the recipients set in /admin/forms/contact and redirects back. A failed email never loses the submission.

Accounts for the public site — tables, authentication and sessions separate from admin users. No predefined roles: each site declares its own types and the theme decides what each can access.

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

Public registration is off (public_registration: false) — by default only admins create accounts. The theme builds the login/register/reset forms against the engine's POST endpoints, always with csrf_field(). csrf_field().

Three independent layers, all native:

• Fixed theme strings embrulhe em t('Read more')wrap in t('Read more'); catalog built by i18n:scan and translated at /admin/translations.
• Structural URLs: slugs of pages, types and taxonomies per language: /blog/post-x becomes /en/news/post-x.
• Per-record content title, slug and fields with *_translations columns and language tabs in the editor itself.

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

The other languages are registered at /admin/languages, each with a URL prefix. In the templates nothing changes: field(), the_title() e option() already resolve the active language with a fallback to the default, so you write the template once.

Non-default language URLs are strict — no translated slug, no URL in that language (no duplicate content for Google). The sitemap emits hreflang only when the translation really exists.

./bin/velk <comando>./bin/velk <command>, from the project root. Almost everything the panel does, the CLI does — that is what lets the AI run the site.

Setup and schema

Content

Useful flags

• --format=json machine-readable output
• --dry-run validate without saving
• --json-stdin --json-stdin — payload via stdin, no shell quoting hell

Deploy

• Shared hosting without SSH: upload the files over FTP/panel — auto-migrate completes the install on the first request.
• With SSH (VPS, cloud, cPanel with terminal): the official skill covers the whole flow — files, database, storage and robots.txt with the production URL.
• Subdirectory: works with no configuration, because the URL helpers prefix the base path themselves.

In production, fill in APP_URL in the .env: o sitemap e o absolute_url() depend on it.

Upgrades

The engine is a versioned dependency, shipped as a tarball with a checksum. The upgrade reads the version in .velk-version, downloads the new one, verifies the sha256 and replaces only the engine paths: theme/, storage/, .env, .htaccess and robots.txt stay as they are. Ask the AI: