Version 0.1.34

webspine documentation

A step-by-step guide for building a site with an AI app, followed by the technical reference for AI apps and developers.

Build your website with an AI app

webspine works with any AI app that can edit project files. It works best with Claude Code in the Claude desktop app, connected to your server as shown below.

Works best with Claude Code on your server

Connect the Claude desktop app to your server over SSH. Claude then builds the website where it will run, so publishing is not a separate step.

In Claude, open Code. Open the environment selector under the prompt box and choose New environment. On the SSH tab, open Host, select Add SSH connection… and enter the login for your server.

ClaudeIllustrated walkthrough
ChatCoworkCode

Environment selector › New environment › SSH › Host

Add SSH connection

Name
My web server
SSH host
deploy@my-domain.com
SSH port
22
SSH key (optional)
~/.ssh/id_ed25519
CancelAdd SSH connection

Still on the SSH tab, choose the new connection and the folder on the server where the website should live, then select Create environment. The first time it connects, Claude installs Claude Code on the server for you.

ClaudeIllustrated walkthrough
ChatCoworkCode

Environment selector › New environment

New environment

LocalSSHCloud
Host
My web server
Folder
~/my-website
CancelCreate environment

Claude now works directly on your server. Describe your website, then open your domain in the browser to look at the result.

ClaudeIllustrated walkthrough
ChatCoworkCode

New session

SSH · My web server~/my-website
Build me a website with webspine.org in this folder.
Read https://www.webspine.org/docs#technical-reference first.

It is for [my idea or business].
I need [my pages].
Make it feel [my preferred style].

The domain [my-domain.com] points to this server. Set it up so the web server serves the public/ folder, and tell me when I can look at it.
my-domain.com

Your website, on your server

Open it in your browser and ask for changes.

Later changes work the same way. Claude edits the files on the server, so there is nothing to upload or deploy afterwards.

ClaudeIllustrated walkthrough
ChatCoworkCode

New session

SSH · My web server~/my-website
Add a page for my latest projects. Back up the site first, then tell me what you changed.
my-domain.comLive. Nothing to upload.

You need the Claude desktop app and a server or hosting package with SSH access, PHP 8.3 or newer and SQLite. Without SSH access, choose Local instead and ask Claude to help you publish the finished site.

Claude Code documentation on SSH sessions

With another AI app

ChatGPT Desktop, OpenCode and similar apps work too. They usually build the site in a folder on your computer, so publishing it is a separate step at the end.

Tell your AI what to build

A portfolio, a studio website, a place for your next project. Describe its purpose, the pages you need, and the style you have in mind. Use this prompt to start.

YOUR FIRST PROMPT
Build me a website using webspine.org.

My website is for: [your idea or business]
It needs these pages: [your pages]
The look and feel should be: [your style]

Create the site and show me a preview so we can refine it together.

Review the preview together

Your AI builds the first version. Look at the preview and tell it what to change: “Make the headline clearer.” “Add my latest work.” “Use warmer colors.” Keep going until the website feels like yours.

Check the details and publish

Review the pages, try the navigation, and check the website on desktop and mobile. Ask your AI to refine the details until the design and content feel right. Your finished website is yours to keep and develop.

Later changes work the same way

New pages, fresh copy, a different design. Come back to your AI, explain your next idea, and let it work on the same website.

Need the details? Open the technical reference
For AI apps and developers

How webspine works

For your AI tool and anyone building or maintaining webspine by hand. Follow the installation guide, understand the project structure, and use the reference below to develop and deploy the site.

Read the versioned framework reference on GitHub
Back to the AI user guide
01 / GET GOING

Quick start

For a new website, get a full bootstrap ZIP from an official stable GitHub release and extract it. A core-only ZIP updates an existing installation; it cannot create a site. You need PHP 8.3+ with pdo_sqlite, openssl for SMTP, and zip for packaging and updates. No Composer, npm, or build step.

Get webspine on GitHub
php core/bin/console.php install
php core/bin/console.php health
php -S localhost:8080 -t public public/router.php

Visit localhost:8080. Installation explicitly creates SQLite tables, records schema version 1, and selects the Starter theme. Re-running it preserves settings and pages. Requests never install or migrate a database.

Use the PHP development server locally. In production, configure your web server with public/ as its only document root.
02 / THE INTENT

Principles

The core goal of webspine is to let you build, extend, and maintain your own website entirely with AI. Familiar code, a readable structure, and explicit contracts give an AI contributor a project it can understand.

Bring your own AI app with access to the project files, such as ChatGPT Desktop, Claude Code, or OpenCode. The project stays independent of any AI vendor; you can also edit every file by hand.

  • Keep the core small and understandable.
  • Keep content and routes in site/, presentation in site/themes/, and capabilities in site/plugins/.
  • Choose providers explicitly. Avoid hidden configuration in the database.
  • Preserve a theme’s identity. Every website can look different.

AI contributors should inspect existing work, make scoped changes, run relevant checks, report gaps, and protect secrets.

03 / A PLACE FOR EVERYTHING

Project structure

core/Framework, bundled providers, tools, tests, and guides
site/Site identity, page definitions, routes, and installation
site/content/Editable PHP content arrays; this website adds English/German catalogs through site-owned localization
site/themes/Templates, shared layouts, scoped CSS, and browser JS
site/plugins/Provider and feature extensions with manifests
config/Private provider selection and credentials
storage/SQLite, update stages, backups, and locks
public/The only web document root
core/bin/Installation, health checks, packaging, and updates
.dist/Generated release ZIPs and checksums
core/tests/Dependency-free integration tests
core/docs/Architecture, deployment, and contributor guidance

The SQLite provider implements storage, settings, pages, and optional Entities CRUD. Plugins declare typed entities and use shared create/read/list/update/delete operations after running php core/bin/console.php entities:install. See core/docs/entities.md and site/plugins/catalog/ for examples. Feature plugins use interfaces, never provider-specific SQL. MariaDB and PostgreSQL adapters will need their own queries, migrations, and data-transfer tooling.

SQLite also supports the optional EntityQueries and EntityIndexes capabilities on the Entities service. Use EntityFilter and EntityQuery for typed filtering, sorting, search() and count(); check provider capabilities explicitly. Declare indexes with defineIndex() and run entities:install to create them. Queries, health checks and core updates never create indexes or rewrite records.

Read the entity query and index reference
04 / CHOOSE EXPLICITLY

Configuration

Copy config/example.php to config/local.php. Keep the local file private. Select providers and enabled feature plugins here, before database access.

'providers' => ['storage' => 'sqlite', 'mail' => null],
'plugins' => [],
'sqlite' => ['path' => 'storage/site.sqlite'],

Select 'mail' => 'smtp' and fill in the SMTP configuration to enable bundled PHPMailer. The provider requires TLS and sends plain-text messages. Mail and feature plugins are disabled by default in the Starter. The optional queued contact example is adopted explicitly; see the contact and queue sections below.

SQLite belongs on local disk with modest write concurrency. Keep the database and update backups outside the document root.

05 / YOUR EXPRESSION

Themes

Duplicate site/themes/starter/, choose a lowercase directory ID, and update theme.json. Keep API version 1 and provide layout.php plus the templates referenced by site/pages.php. The shared layout wraps every page. Edit wording in site/content/, page titles in site/pages.php, and identity in site/meta.php; theme files own markup and styles.

php core/bin/console.php theme your-theme

The active theme is stored by the settings service. Assets are served only from the selected theme’s assets/ folder through a constrained route. Scope CSS under a theme class, escape strings with e(), and keep JavaScript progressively enhanced.

PHP themes and plugins execute trusted code. Review them before installing; they are not sandboxed.

Reusable PHP components live in site/themes/<id>/components/. Pass explicit props with $app->theme->component(); components receive $props and $ui, without page variables or services. Pages and layouts also receive $ui for nested component(), id(), and assetUrl() calls. Use e($ui->assetUrl('style.css')) for a theme asset URL with a content-hash version. Page and layout scopes are separate: pass shared values in render data and access reserved-name collisions through $data. See core/docs/site.md for examples and rendering-lifecycle rules, including refresh() after manual settings or file changes on a reused App.

Page paths and explicit redirects.

Declare an optional path in site/pages.php to register a GET/HEAD page route. slash accepts preserve (the default), strip or append; strip/append add a 308 redirect for the alternate slash form and retain the raw query string. Remove the equivalent manual GET route before adopting a path: duplicate exact or matching pattern routes fail. Existing site routes remain intact during core updates. Use Response::redirect() for validated local redirects; page paths do not generate SEO canonical tags or multilingual routes.

// site/pages.php
'about' => ['path' => '/about', 'slash' => 'strip',
    'template' => 'page', 'title' => 'About'],
Read the page routing and redirect guide
06 / EXPLICIT CONNECTIONS

Plugins and services

Custom plugins live in site/plugins/; bundled providers live in core/plugins/. IDs must be unique across both directories. Every plugin declares its ID, semantic version, API, and dependencies in plugin.json. The entry file returns an object implementing Webspine\Contracts\Plugin.

{
  "id": "my-feature", "version": "0.1.0", "api": 1,
  "dependencies": {"field-notes": "0.1.0"}
}
public function register(App $app): void {
    $pages = $app->services->get(Pages::class);
    $app->router->get('/hello', function () use ($pages, $app) {
        $page = $pages->find('hello');
        return $app->theme->render('page', [
            'title' => $page['title'], 'body' => $page['body'],
        ]);
    });
}

The registry accepts implementations of declared interfaces and rejects duplicate registrations. Providers register services; feature plugins consume them. Providers must be selected in private configuration rather than loaded implicitly as dependencies.

GET/POST handlers can receive Webspine\Request; pattern handlers receive ($matches, $request). Use query(), header(), form(), or json() and validate types. Bodies are limited to 64 KiB and queries to 8 KiB; form() supports URL-encoded bodies, not multipart uploads. POST routes do not add authentication, CSRF, validation, or abuse protection automatically. The copied contact example provides its own session, validation and abuse protection, and queues delivery through the bundled job-queue.

Visit the working example plugin

Discover plugin commands.

Enabled trusted plugins can register local operator commands through cli.register and ConsoleCommands. help lists their commands; help <command> shows usage. help --core avoids booting site configuration for diagnosis. Command handlers own argument validation and storage setup; discovery never installs or migrates storage. The legacy core/plugins/job-queue/cli.php commands remain supported.

php core/bin/console.php help
php core/bin/console.php help job-queue:work
php core/bin/console.php help --core
Read the plugin command and cron guide
OPTIONAL FEATURES

Contact forms that save first.

Give visitors a way to reach you. The copyable contact example saves valid messages to the durable job queue before a background worker sends them through your configured Mail provider. A success notice means saved for delivery. The Starter does not enable a form automatically.

Copy plugin.php, plugin.json, FormText.php, ContactForm.php and MailDelivery.php from core/docs/examples/contact-form/ into site/plugins/contact-form/. Copy the example template, styles and content into your selected theme and site content, or adapt your existing presentation. Merge the settings below into private configuration, append the plugin to your existing list, configure SMTP and install queue storage. The bundled job-queue dependency loads automatically.

// Merge into private config/local.php; preserve other settings.
'plugins' => ['contact-form'],
'contact_form' => [
    'recipient' => 'you@example.com',
    'path' => '/contact-example',
    'retry' => ['max_attempts' => 30],
],

Since 0.1.12, a matching expired form token preserves safe input and provides a fresh token for review and resubmission. Missing or foreign tokens discard input. Exact successful replays in the same session redirect to success without adding another job. Field limits match native browser UTF-16 code units; new payload version 2 remains compatible with delivery of existing version 1 jobs.

New contact jobs default to 30 total delivery attempts. Configure retry.max_attempts as an integer 1–100. Exponential waits grow from one minute to one hour; with 30 attempts, the final attempt is scheduled about 24 hours 3 minutes after the first, excluding transport time and cron delays. Existing jobs retain their saved attempt limit. SMTP delivery is at least once, so crash-related duplicate delivery remains possible.

The current copyable example saves the validated email field as a Reply-To snapshot. Bundled SMTP supports MailWithReplyTo and keeps the fixed recipient and configured From identity. Set contact_form.reply_to_field to another email field, or null to disable it for new jobs. Providers without the capability fall back to ordinary Mail; the visitor email stays in the body. Older queued jobs without a Reply-To snapshot keep their original behavior. Reply-To does not authenticate the visitor or guarantee delivery.

Core updates preserve copied site plugins. To adopt newer contact features, review and copy the current example files, including FormText.php, with compatible content keys and the declared job-queue dependency. Preserve private settings, templates and existing queued data; no queue schema migration is required. This website uses its own adapted plugin at /feedback and /de/feedback; a core upgrade alone does not add the new example’s Reply-To behavior to that copy.

Read the contact-form adoption guide
OPTIONAL FEATURES

A reusable queue for background work.

The optional bundled job-queue plugin separates durable saving from background processing. Consumers register handlers for named, versioned job types. Payloads are extensible JSON objects, bounded to 64 KiB and limited depth. Dedupe keys reject conflicting data; leased claims and claim tokens protect concurrent workers. Generic jobs default to five attempts, independently of the contact form.

Install storage explicitly, then schedule work using an absolute script path and your PHP executable, for example every minute. Each invocation processes at most ten jobs. Missing or paused handlers consume no attempts. There is no web worker endpoint and no sending during a form request. Keep storage/job-queue private and writable by the trusted web/CLI group.

php core/bin/console.php job-queue:install
php core/bin/console.php job-queue:status
php core/bin/console.php job-queue:work
php core/bin/console.php job-queue:health
php core/bin/console.php job-queue:retry <job-id>
php core/bin/console.php job-queue:prune 30

Since 0.1.13, status includes pending/due ages, expired leases and worker start/finish activity. The private health command returns JSON warnings and a nonzero exit status when work needs attention. job_queue.stale_after_seconds defaults to 900; allowed integers are 60–604800. Future scheduled retries are excluded from overdue warnings. Monitor the command externally; a heartbeat does not prove mail delivery. Public /health stays independent of the delivery backlog.

CLI work automatically removes up to 1,000 completed jobs per normal invocation once they are at least 30 days old, even when no delivery jobs are ready. job_queue.retention_days accepts 1–3650 or null to disable automatic cleanup. Pending, processing and failed jobs are never removed automatically. Review failed jobs before retrying or pruning; explicit prune 30 also removes terminal-failed jobs beyond its retention period. Cleanup removes payloads and dedupe history; manage backup retention separately. Keep the worker scheduled and use consistent SQLite backups for WAL databases.

'job_queue' => [
    'stale_after_seconds' => 900,
    'retention_days' => 30, // 1–3650; null disables automatic cleanup.
],
Read the queue and monitoring guide
OPTIONAL FEATURES

Simple analytics, without visitor tracking.

spine-analytics is an optional plugin bundled under core/plugins/spine-analytics. It counts aggregate requests and page visits without browser scripts, cookies, visitor IDs or stored IP addresses. These are request counts, not unique visitors. Collection and browser reporting are disabled by default.

Append spine-analytics to your existing plugin list and merge the settings below. Allowlist fixed public paths only, enable collection deliberately and run its installer explicitly. It owns a separate SQLite database at storage/spine-analytics/counts.sqlite; normal installation and core updates do not initialize analytics storage. Never also install a site plugin with the same ID.

// Append spine-analytics to the existing plugins list.
'spine_analytics' => [
    'enabled' => true,
    'preview' => false,
    'report_enabled' => false,
    'pages' => ['/', '/docs'],
],
php core/plugins/spine-analytics/cli.php install
php core/plugins/spine-analytics/cli.php report 30

Aggregates retain 90 UTC calendar days and expire on the next counted request. Queries and fragments are discarded; unlisted paths are combined as [other]. Optional coarse device metrics use request headers without fingerprinting. Only requests reaching PHP count; assets, /health and /_insights are excluded. Protect exports and backups separately.

Keep preview=false in production. A browser report at /_insights requires report_enabled=true, HTTPS and a configured password hash; follow the bundled guide to set it up. CLI reports and offline HTML exports remain private. Collection failures do not replace website responses.

Read the analytics installation and privacy guide
07 / PRESERVE WHAT YOU MAKE

Core updates

Core releases carry an exact file inventory with SHA-256 hashes, version, PHP minimum, and API compatibility. Updates validate and stage the archive, check compatibility and health, then activate under an exclusive lock. Failed health checks roll back changed files. A persistent recovery journal blocks requests after an interrupted activation until recovery.

php core/bin/console.php package
php core/bin/console.php update /path/to/core-release.zip
php core/bin/console.php rollback
php core/bin/console.php recover

Site files, themes, custom plugins, config, and data are preserved. Bundled providers in core/plugins/ update with the framework. Create your website from a bootstrap once; use core release archives for framework updates. Pulling or copying the upstream repository over a customized site does not provide this preservation guarantee. Core updates do not migrate databases. Back up the site separately before upgrading. Drain production workers and reset OPcache after activation.

Hashes detect corruption; they do not authenticate a release. Only apply local archives from a source you trust. Signed online updates and separate extension updates are planned.
08 / OUT IN THE WORLD

Deployment

Set your Apache or nginx document root to public/. Route requests to index.php; the included Apache configuration requires mod_rewrite and override permissions. Disable directory indexes and deny arbitrary PHP files. See core/docs/deployment.md for copyable Apache, nginx, and CloudPanel examples and real-server test instructions.

The PHP worker needs read access to framework and extensions, and write access to storage/. Only the operator performing an update needs write access to framework files. Use HTTPS, back up data, and keep config/local.php out of version control.

For a bootstrap ZIP including the starter theme and providers, run php core/bin/console.php package --full. A normal core release contains only managed framework files.

Deploy at the domain root, with PHP 8.3+ for both CLI and web workers. In CloudPanel, exclude /assets/ from the generic static-file regex with ^(?!/assets/) so theme assets reach PHP; they live outside public/. CORS and HTTP/3 headers are separate hosting settings. Verify both frontend and backend routing. Restart PHP-FPM or Apache PHP workers after an update to clear their OPcache; a CLI opcache_reset() does not clear the web-worker cache.

New Starter sites begin with indexable set to false in site/meta.php. Set it to true when ready to launch, then check deployed robots directives. Custom themes own their indexing behavior. Core does not generate robots.txt, a sitemap, or canonical URLs automatically.

09 / DO THE BORING THINGS WELL

Quality and security

Templates must escape untrusted output, and SQLite queries are parameterized. Asset routes are confined to the selected theme and approved file types. The minimal Starter uses system fonts, a shared layout, reusable components, visible keyboard focus, a skip link, and responsive layouts; it works without JavaScript. Accessibility and interaction in a custom theme remain the site’s responsibility.

php core/tests/run.php
php site/tests/run.php

Framework checks use independent fixtures; keep website-specific checks in site/tests/run.php and adapt them to your site. Run session-based contact checks in a subprocess or HTTP fixture before printed progress can interfere with headers. Coverage includes typed entity queries, page routing, response headers, templates, assets, queue retention, archive integrity and rollback. The optional Docker hosting suite checks Apache and nginx/PHP-FPM; see core/docs/deployment.md. WCAG 2.2 AA is the target; a full assistive-technology audit remains to be done.

Writing endpoints own validation, CSRF, and abuse protection. Privileged actions also need authentication and authorization. The Starter has no admin editor or uploads; the optional contact-form example supports anonymous inquiries and grants no editing privileges.

Security headers and external embeds.

Responses default to nosniff, strict-origin-when-cross-origin and a Content Security Policy restricted to same-origin resources, with data: images allowed and framing by other sites blocked. Explicit response headers override defaults regardless of header-name case. To allow an embed, copy the full default CSP and extend only the necessary directive on that one response, for example frame-src for one trusted origin. A custom CSP replaces the entire default policy. Avoid wildcards, unsafe-inline and unsafe-eval; account for external visitor requests in your privacy and consent choices. Response::DEFAULT_HEADERS and emittedHeaders() expose the defaults and emitted header set for tests.

Read the security header and CSP examples
10 / THE STATE OF THE SPINE

Status and roadmap

Built

Routing and responses with explicit page paths and slash redirects; request context and opt-in POST; plugin contracts, hooks and console commands; SQLite settings, pages, Entities CRUD, typed queries and explicit indexes; themes and nested components; versioned assets; SMTP with optional Reply-To, aggregate analytics and a durable queue; a copyable queued contact form with token recovery and configurable retries; private queue monitoring and completed-job retention; reversible core updates and independent framework checks.

Planned

MariaDB / PostgreSQL adapters and data transfer; separate extension updates; signed online updates; admin and content editing; authentication; a general form builder and uploads.