API Data

Data

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

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

Class	What it is
Caligrafy\Model	Class Model is the base model from which the application models can be extended
Caligrafy\Query	Builds one SQL statement with bound values only.
Caligrafy\Database	The Database class handles all database connections and global functions that interface directly with the database
Caligrafy\Migrations	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	Class that validates inputs
Caligrafy\Cache	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	#[Caligrafy\Lazy] on a relation method of a model (2.26.0): it may load lazily, without [ERROR 2004] or a warning
Caligrafy\LazyLoadingException	Thrown in development when a relation loads lazily on one of several models a query read ([ERROR 2004], 2.26.0)

class Caligrafy\Model

Class Model is the base model from which the application models can be extended

Its 24 public methods have a page of their own: Caligrafy\Model.

class Caligrafy\Query

Builds one SQL statement with bound values only.

Its 47 public methods have a page of their own: Caligrafy\Query.

class Caligrafy\Database

The Database class handles all database connections and global functions that interface directly with the database

Its 16 public methods have a page of their own: Caligrafy\Database.

class Caligrafy\Migrations

namespace Caligrafy;

class Migrations

Source: framework/core/Migrations.php:23

Class Migrations 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). A file is never run twice: change the database with a new file, not by editing one that ran (status shows it as "changed", and deploy warns). The deploy step (php caligrafer.php deploy) runs them after the create_db.sql scripts. Forward only: undo a change with a new migration.

The statements of a file are split on ; outside quotes and comments. A file stops at its first failing statement: it is not recorded, the statements before it stay applied (MySQL commits a CREATE or ALTER at once), so write each file so that it can run again (IF NOT EXISTS), or keep one change per file.

Constants

• FOLDER = 'application/migrations'
• TABLE = 'caligrafy_migrations'
• PATTERN = '/^(\d{1,14})_([A-Za-z0-9_]+)\.sql$/'

Methods

• ->__construct()
• ->files()
• Migrations::install()
• ->status()
• ->run()
• ->make()
• Migrations::statements()

->__construct()

public function __construct($root = '.')

No doc comment.

Parameters

• $root, default '.'

Source: framework/core/Migrations.php:31

->files()

public function files()

The migration files, in order: name => path (relative to the project)

Source: framework/core/Migrations.php:39

Migrations::install()

public static function install()

Creates the table that records the migrations that ran

Source: framework/core/Migrations.php:65

->status()

public function status()

Every migration with its state: ran, pending, or changed (it ran, then its file was edited)

Returns array: of ['name', 'path', 'state', 'ran_at']

Source: framework/core/Migrations.php:75

->run()

public function run(?callable $say = null)

Runs the pending migrations, in order; stops at the first that fails (the exception names it)

Parameters

• $say ?callable, default null

Returns array: the names that ran

Source: framework/core/Migrations.php:95

->make()

public function make($name, $at = null)

Writes a new, empty migration: application/migrations/<YYYYMMDDHHMMSS>_<name>.sql

Parameters

• $name
• $at, default null

Returns string: its path

Source: framework/core/Migrations.php:125

Migrations::statements()

public static function statements($sql)

The statements of a SQL script: split on ; outside quotes ('...', "...", ...) and comments (--, #, /* */), comments removed, empty statements dropped

Parameters

• $sql

Source: framework/core/Migrations.php:147

class Caligrafy\Validator

namespace Caligrafy;

class Validator extends \GUMP

Source: framework/core/Validator.php:29

Class that validates inputs

Constants

• MESSAGES = array('exists' => 'There is no such {param}', 'unique' => 'This {param} is already used')

Methods

• ->__construct()
• Validator::registerRules()
• Validator::exists()
• Validator::unique()
• Validator::normalize()
• ->validate()
• ->get_errors_array()
• ->check()

->__construct()

public function __construct(string $lang = 'en')

No doc comment.

Parameters

• $lang string, default 'en'

Source: framework/core/Validator.php:36

Validator::registerRules()

public static function registerRules()

Registers the rules exists and unique with GUMP, once. A rule of the same name that the app added first is kept.

Source: framework/core/Validator.php:45

Validator::exists()

public static function exists(array $params, $value)

Whether a value is in table.column (the rule exists)

Parameters

• $params array
• $value

Source: framework/core/Validator.php:71

Validator::unique()

public static function unique(array $params, $value, array $input = array())

Whether a value is not yet in table.column (the rule unique), ignoring the row whose column $params[1] equals the input $params[2]

Parameters

• $params array
• $value
• $input array, default array()

Source: framework/core/Validator.php:81

Validator::normalize()

public static function normalize($rules)

The rules as GUMP reads them: unique's extra arguments joined with ; (GUMP keeps one , only) and current_year replaced by the year of today

Parameters

• $rules string|array: 'required|max_numeric,current_year' (or GUMP's array form, kept as it is)

Source: framework/core/Validator.php:101

->validate()

public function validate(array $input, array $ruleset)

No doc comment.

Parameters

• $input array
• $ruleset array

Source: framework/core/Validator.php:122

->get_errors_array()

public function get_errors_array()

The errors by field; exists and unique say what is missing or taken: "There is no such author", "This email is already used" (GUMP::set_error_message() or the per-field messages replace them)

Source: framework/core/Validator.php:131

->check()

public function check($data, $rules = array(), $filters = array())

No doc comment.

Parameters

• $data
• $rules, default array()
• $filters, default array()

Source: framework/core/Validator.php:172

class Caligrafy\Cache

namespace Caligrafy;

class Cache

Source: framework/core/Cache.php:25

Class Cache (2.18.0)

$rates = Cache::remember('exchange-rates', 600, fn () => $this->fetchRates());   // at most once every 10 minutes
Cache::put('report:2026-11', $rows, 3600);  Cache::get('report:2026-11', []);  Cache::forget('report:2026-11');

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 every server), file (the default without a database: a private folder of the temporary directory, of one server and one system user, so the command line and the web server each have their own) or off (nothing is kept, remember() always runs its function). Values are stored as JSON: strings, numbers, booleans, null and arrays (an object comes back as an array). $seconds null keeps a value until it is forgotten or flushed. php caligrafer.php cache clear empties the store.

Constants

• TABLE = 'caligrafy_cache'
• STORES = array('file', 'database', 'off')

Methods

• Cache::store()
• Cache::get()
• Cache::has()
• Cache::put()
• Cache::forever()
• Cache::remember()
• Cache::forget()
• Cache::flush()
• Cache::clearMemory()

Cache::store()

public static function store()

The store in use: file, database or off

Source: framework/core/Cache.php:36

Cache::get()

public static function get($key, $default = null)

No doc comment.

Parameters

• $key
• $default, default null

Source: framework/core/Cache.php:70

Cache::has()

public static function has($key)

No doc comment.

Parameters

• $key

Source: framework/core/Cache.php:76

Cache::put()

public static function put($key, $value, $seconds = null)

Keeps $value for $seconds (null: until forgotten)

Parameters

• $key
• $value
• $seconds, default null

Source: framework/core/Cache.php:84

Cache::forever()

public static function forever($key, $value)

Keeps $value forever (until forgotten or flushed)

Parameters

• $key
• $value

Source: framework/core/Cache.php:123

Cache::remember()

public static function remember($key, $seconds, callable $make)

The cached value, or the result of $make, kept for $seconds

Parameters

• $key
• $seconds
• $make callable

Source: framework/core/Cache.php:131

Cache::forget()

public static function forget($key)

No doc comment.

Parameters

• $key

Source: framework/core/Cache.php:142

Cache::flush()

public static function flush()

Empties the store

Returns int|null: how many values were removed (null when unknown)

Source: framework/core/Cache.php:159

Cache::clearMemory()

public static function clearMemory()

Forgets this request's copies (tests, a long worker)

Source: framework/core/Cache.php:179

class Caligrafy\Lazy

namespace Caligrafy;

class Lazy

Source: framework/core/Model.php:705

#[Caligrafy\Lazy] on a relation method of a model (2.26.0): it may load lazily, without [ERROR 2004] or a warning

No public methods.

class Caligrafy\LazyLoadingException

namespace Caligrafy;

class LazyLoadingException extends \LogicException

Source: framework/core/Model.php:697

Thrown in development when a relation loads lazily on one of several models a query read ([ERROR 2004], 2.26.0)

No public methods.