API Reference

API reference

Caligrafy Quill 2.26.0: every public class, method and helper function of the framework, generated from the source at each release by php qa/build-api-reference.php. Each method shows its signature, its doc comment as written in the code, its parameters, what it returns and the line of the source it is on.

The guides of the wiki explain how to use these classes; start with How Caligrafy works.

Routing and requests

Declaring requests and reading them: routes, the request, forms, downloads, webhooks, web-only actions, errors and flash messages.

Class	Methods	What it is
Caligrafy\Route	30	Class that builds the routing logic of the framework
Caligrafy\AuthRoutes	15	Route::auth() (after Auth::authentication('User', 'users') in web.php) registers, with the views of the authentication module (application/views/Auth/login.pug and register.pug)
Caligrafy\Request	13	(no doc comment)
Caligrafy\Web	7	A capability declared #[Capability(..., webOnly: true)] and served by Route::action() may return one of these instead of plain data, to choose what the browser gets
Caligrafy\Action	2	Route::action('/connect', 'cloud_connect') answers a request with a capability declared webOnly: true, for what a page or a form cannot say: a sign-in between two sites, a session that decides where to go, a gate, a ...
Caligrafy\Form	11	Route::form('/books', 'create_book', ['success' => '/books/{id}', 'flash' => 'Book added']) answers the form's POST (or its PUT / DELETE through _method) with a capability, without a controller: 1. the CSRF token of the ...
Caligrafy\Download	13	Route::download('/books.csv', 'list_books', ['as' => 'csv', 'filename' => 'books.csv']) answers a GET with the result of a read-only capability as an attachment, without a controller: - inputs: the query string and the ...
Caligrafy\Webhook	3	Route::webhook('/stripe/events', 'record_payment', ['verify' => 'stripe']) answers the POSTs of another service with a capability, without a controller: - no CSRF token (the sender has no session): the signature of the ...
Caligrafy\Uploads	12	A capability declares a file input with the rule file, an optional allow-list and an optional maximum size
Caligrafy\Throttle	7	The counts are kept in the Cache (CACHE_STORE: the caligrafy_cache table or a private folder, shared by every session, so that a new cookie does not start again), or in the session when the cache is off.
Caligrafy\Errors	6	The Errors Class is the dictionary of all the error messages in the system
Caligrafy\Flash	5	Route::form() puts the field errors, the old input and a message here before it redirects; the page of the next request reads them with the view helpers errors($field), old($field) and flash($key), then they are gone.
Caligrafy\Context	13	Built by the channel adapters (web pages, REST, MCP, CLI) and read by the services: a service never looks at the request, the session or the headers itself.

Controllers and views

Rendering pages: the controller base class, the page controller of Route::page, views and design styles.

Class	Methods	What it is
Caligrafy\Controller	17	Parent Class that defines the properties and methods of a controller
Caligrafy\PageController	6	Route::page('/books/{id}', 'Books/show', ['data' => ['book' => 'get_book']]) renders a view through this controller: 1. access: 'signedIn' => true sends visitors to /login; 'level' => N also sends people below level N to
Caligrafy\View	5	Class View is the view renderer of the application
Caligrafy\Designs	12	A style is a DESIGN.md and the override stylesheet written from it, public/css/designs/<name>.css.
Caligrafy\HttpCache	4	A capability declared with cache (#[Capability(..., readOnly: true, public: true, cache: 30)]) answered over REST, or a page declared with Route::page(..., ['cache' => 30]), is sent with Cache-Control: public, ...

Services and capabilities

Build once: services, the capability registry, errors, the container, personal access tokens and the audit log.

Class	Methods	What it is
Caligrafy\Service	4	Extend it in application/services/, declare the inputs and implement handle()
Caligrafy\Capability	1	#[Capability(name: 'create_book', description: 'Adds a book to the catalog', scope: 'books:write')] on a class that extends Caligrafy\Service.
Caligrafy\Capabilities	12	A capability is a class of application/services/ that extends Service and carries #[Capability(...)].
Caligrafy\ServiceError	8	A service throws it to refuse a call.
Caligrafy\Container	10	Capabilities are made by the container, so a service asks for what it uses in its constructor
Caligrafy\Tokens	11	A token is cq_<id>_<secret>: shown once when it is created, stored only as a SHA-256 hash in caligrafy_tokens with a name, an optional owner (users.id), its scopes, an optional expiry, the last use and a revocation ...
Caligrafy\Audit	2	One row per capability call that changes data, and per refused call: when, who (a user, a token, the CLI), through which channel, which capability and the outcome.

Data

Models, the query builder, the database connection, migrations, validation and the cache.

Class	Methods	What it is
Caligrafy\Model	24	Class Model is the base model from which the application models can be extended
Caligrafy\Query	47	Builds one SQL statement with bound values only.
Caligrafy\Database	16	The Database class handles all database connections and global functions that interface directly with the database
Caligrafy\Migrations	7	application/migrations/<number>_<name>.sql: php caligrafer.php migrate runs, in number order, the files that never ran on this database, and records each one in caligrafy_migrations (its name, its sha256, when).
Caligrafy\Validator	8	Class that validates inputs
Caligrafy\Cache	9	CACHE_STORE in .env: database (the default with DB_ACTIVATE=true: the caligrafy_cache table, which the deploy step and php caligrafer.php platform install create, shared by the web server, the queue, scheduled jobs and ...
Caligrafy\Lazy	0	#[Caligrafy\Lazy] on a relation method of a model (2.26.0): it may load lazily, without [ERROR 2004] or a warning
Caligrafy\LazyLoadingException	0	Thrown in development when a relation loads lazily on one of several models a query read ([ERROR 2004], 2.26.0)

Sign-in

Users and sessions, passkeys and face login.

Class	Methods	What it is
Caligrafy\Auth	13	Class that defines the properties and methods of an authentication mechanism for UI and API
Caligrafy\Passkey	12	Passkey wraps lbuchs/webauthn (MIT, no dependencies besides ext-openssl).
Caligrafy\PasskeyException	0	(no doc comment)
Caligrafy\FaceLogin	9	Face login checks used with FaceDetector.liveness() (public/js/services/detect.js)
Caligrafy\FaceLoginException	0	(no doc comment)

Jobs, notifications and mail

Scheduled jobs, background jobs, web push and email notifications, mail.

Class	Methods	What it is
Caligrafy\Scheduler	13	An app declares its jobs in application/config/schedule.php: each one calls one capability with fixed inputs on a fixed rhythm (every: 1m...1d, or a five-field cron in a timezone).
Caligrafy\Queue	6	A job is a capability and its input, kept in the caligrafy_jobs table (php caligrafer.php platform install, or the deploy step, creates it).
Caligrafy\Notify	20	Notify::user($userId, ['title' => ..., 'body' => ..., 'url' => ..., 'tag' => ..., 'urgency' => ...]) sends to every channel the user turned on and logs the result (caligrafy_notifications: never the body; kept 30 days): ...
Caligrafy\Mail	2	The Mail class handles all emails sent from the framework

Payments

Stripe and cryptocurrency payments.

Class	Methods	What it is
Caligrafy\Payment	12	The Payment handles all payment transactions
Caligrafy\CryptoPayment	9	CryptoPayment accepts crypto payments (USDC) through the Coinbase Business Checkouts API.

AI

OpenAI, open models through OpenAI-compatible providers, the OpenAI Assistants and Watson.

Class	Methods	What it is
Caligrafy\OpenAI	5	The OpenAI class handles all exchanges with the OpenAI models (text and images)
Caligrafy\Agent	13	The Agent class talks to open models through OpenAI-compatible providers: Groq (default, through groq-php), Together AI, Fireworks AI, OpenRouter, a local Ollama or any custom endpoint.
Caligrafy\Assistant	12	The Assistant class runs conversations with OpenAI models through the Responses and Conversations APIs.
Caligrafy\Watson	11	The Watson class handles all exchanges with the Watson Assistant

Interfaces: REST, the JS client and MCP

The channels that serve the capabilities besides web pages.

Class	Methods	What it is
Caligrafy\Rest	4	Answers HTTP requests with capabilities, in JSON: - Route::capability('POST', '/books', 'create_book') maps one route to one capability - Route::capabilities('/capabilities') adds GET /capabilities (what the caller may ...
Caligrafy\Client	2	One ES module, no dependency, for the Vue apps, the Vite SPA and Node scripts: one async function per capability (create_book becomes createBook) plus call(name, input) and capabilities().
Caligrafy\Mcp\Http	3	One JSON-RPC message per POST, answered with application/json (no event stream: every tool answers at once).
Caligrafy\Mcp\Server	6	JSON-RPC 2.0 messages of MCP, independent of the transport (Http for Streamable HTTP, caligrafer mcp for stdio): initialize, ping, tools/list, tools/call; notifications get no answer.
Caligrafy\Async\Kernel	5	What the async server runs, whatever server it is: boot() once per process (settings, constants, the class map, the application's config and container, the capabilities), then handle() for each request, one at a time ...
Caligrafy\Async\Eligibility	3	The async server keeps the application in memory and answers many requests from one process, so a capability it runs must not keep anything from one caller to the next, nor talk to the web server's request directly.
Caligrafy\Async\WorkermanServer	1	Workerman (pure PHP, composer require workerman/workerman: php caligrafer.php add async) keeps a few processes that each hold the application in memory (Kernel::boot) and many open connections, answering one request at ...

Snap

Snap Cards and the assistant (namespace Caligrafy\Snap): cards built from what capabilities declare, the conversation, the planner and the setup.

Class	Methods	What it is
Caligrafy\Snap\Cards	16	Snap Cards (2.23.0): every card is built from what a capability already declares
Caligrafy\Snap\Hints	3	Snap Cards work without any hint: every card is built from what a capability declares (its rules, descriptions, readOnly and destructive).
Caligrafy\Snap\Views	7	How a Show card looks, best first (2.25.0): 1. its card view: application/views/snap/<capability>.pug, a Pug view made for the card, in the app's own markup and
Caligrafy\Snap\Designer	5	A capability shown through its own page uses that page (Snap\Views).
Caligrafy\Snap\Conversation	15	The Snap shell's two spaces (2.23.0)
Caligrafy\Snap\Planner	4	The Snap shell's planner (2.23.0): Claude reads what the person typed or said and answers with cards.
Caligrafy\Snap\Flow	2	The next card for a capability and its inputs, the same whoever asks (a card that is sent, the shell's fast path, the model's choice): one place decides, so the planner can never take a shortcut around consent.
Caligrafy\Snap\Input	1	The inputs of a card arrive as an object, or its JSON (agents and addresses send JSON text): this gives the plain values only (a nested object or list is left out: a card's inputs are scalars).
Caligrafy\Snap\Reads	2	The reads of one request, once (2.23.0): Home asks the same lists for its alerts, insights and picks; each runs once per person per request.
Caligrafy\Snap\Say	2	The assistant's line after every action (2.23.0): whatever the person did (sent a form, picked a choice, confirmed, opened a row, undid, saved a shortcut), the answer carries what the assistant says about it, shown in ...
Caligrafy\Snap\Consent	3	Snap consent (2.23.0): nothing that changes data runs from a card until the person confirms it.
Caligrafy\Snap\Offers	13	Offer: Suggestion and Offer: Routine (2.23.0): the assistant notices what a person does again and again, only if they turned noticing on, and offers to help.
Caligrafy\Snap\Shortcuts	5	Go: Shortcut cards (2.23.0): a request a person saved (a capability with its inputs), run with one click.
Caligrafy\Snap\Tasks	5	Track: Task cards (2.23.0): work that runs in the background for one person.
Caligrafy\Snap\Discover	2	Discover (2.23.0): Home surfaces the things this application is about, to invite browsing, the way a shop surfaces products.
Caligrafy\Snap\Setup	2	install: the tables (framework/settings/platform.sql), a starter application/config/snap.php when there is none, then the two lines to add by hand (they are the app's own files): Route::snap(); in web.php, and the ...
Caligrafy\Snap\Shell	5	The Snap shell's fast path (2.23.0): what it can answer without a model, at once and for free

Testing

The base class of the tests of an application (tests/, php caligrafer.php test).

Class	Methods	What it is
Caligrafy\Testing\TestCase	9	Test what the app does through its capabilities, as the pages, REST, the JS client and agents reach them

Framework and tooling

The framework bootstrap and what the caligrafer command runs: the CLI, doctor, update, upgrade, deploy, Cloud, quickstart and the plugin copy.

Class	Methods	What it is
Caligrafy\Features	14	The SDKs that only some applications use are no longer in Caligrafy's composer.json (they are suggested): a project adds the one it needs with php caligrafer.php add <feature>, which runs composer require with the ...
Caligrafy\FeatureMissing	0	A feature whose SDK (or files) this project does not install: the message names the command that adds it
Caligrafy\Framework	3	Class Framework that loads the entire framework Framework loader
Caligrafy\Loader	2	Class Loader loads any additional librairies and helpers needed per module Framework loader loads any additional librairies and helpers needed per module
Caligrafy\ClassMap	10	Before 2.18.0 the first unknown class of a request loaded every PHP file of framework/core, framework/database, framework/interfaces, application/ and tests/.
Caligrafy\Caligrafer	4	Class Caligrafer: the framework as the command line starts it (php caligrafer.php): settings, constants and the class map, without routes or a session cookie
Caligrafy\Doctor	6	Every check is read-only: it lists, reads or connects, it never creates, charges or sends anything (the only exception is Watson when its assistants cannot be listed: a session is opened and closed right away).
Caligrafy\Updater	4	php caligrafer.php update [<version>] downloads the project's release (Framework::VERSION) and the target release (the latest by default), then: 1. framework/ and claude-plugin/ are the framework's: replaced whole ...
Caligrafy\Upgrader	5	Compares application/ with framework/settings/application and reports or applies the template updates.
Caligrafy\Deployer	7	1. waits for the database (a new server starts its database at the same time as the app) 2. creates the framework tables (framework/settings/platform.sql, safe to run again) 3. runs every ...
Caligrafy\CloudClient	3	Calls the capabilities of Caligrafy Cloud (POST <url>/capabilities/<name>) with a personal access token of the account.
Caligrafy\Quickstart	10	Every step can be run again: it only does what is missing.
Caligrafy\PluginSource	7	A project enables the Claude Code plugin of its own claude-plugin/ folder through .claude/settings.json: a plugin source (a "marketplace", declared in .claude-plugin/marketplace.json) at "./", and the plugin ...

Helper functions

65 global functions of framework/helpers: generateKey(), generateToken(), encryptDecrypt(), isSessionExpired(), saveInSession(), clearFromSession(), scripts(), design_stylesheet(), copyright(), keywords(), metadata(), session(), caligrafySessionNeeded(), caligrafySessionReady(), caligrafySessionMustSave(), caligrafySessionStart(), caligrafySessionSnapshot(), caligrafySessionShutdown(), view(), api(), findKey(), recursive_filter(), loadConstantFromArray(), terminateSession(), getGlobalInformation(), isAllowedUpload(), uploadFile(), deleteFile(), isJson(), sanitize(), request(), connect(), import(), parsePath(), currentRoute(), currentBind(), startWith(), endWith(), sanitizePath(), associate(), bindRouteToVar(), parseRoute(), _require_all(), singularize(), methodField(), csrf(), errors(), old(), flash(), authorize(), authorized(), unauthorize(), user(), guard(), logout(), imageCanva(), load_script(), redirect(), getRelativeTime(), rearrange(), httpFile(), httpRequest(), now(), sendMail(), arraySort().

---

86 classes, 677 public methods, 65 functions.