API Route

Caligrafy\Route

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.

Part of Routing and requests.

namespace Caligrafy;

class Route extends \stdClass

Source: framework/core/Route.php:20

Class that builds the routing logic of the framework

Constants

• EXAMPLE_CONTROLLERS_NAMESPACE = 'Caligrafy\\Controllers': Namespace of the example controllers shipped in application/controllers/core (AIController, AuthController...)

Public properties

• public static $currentRoute: string $currentRoute defines the currently run route
• public static $currentBind: string $currentBind defines variables bound to the route

Methods

• Route::run()
• Route::evaluate()
• Route::bind()
• Route::execute()
• Route::resolveController()
• Route::get()
• Route::post()
• Route::put()
• Route::delete()
• Route::capability()
• Route::page()
• Route::pages()
• Route::action()
• Route::bots()
• Route::capabilities()
• Route::notifications()
• Route::snap()
• Route::mcp()
• Route::form()
• Route::auth()
• Route::webhook()
• Route::download()
• Route::redirect()
• Route::withQuery()
• Route::redirectTarget()
• Route::isWebhook()
• Route::isMcp()
• Route::routes()
• Route::reset()
• Route::handler()

Route::run()

public static function run()

Runs the routes based upon a request

Source: framework/core/Route.php:102

Route::evaluate()

public static function evaluate()

Evaluates the route and binds it with variables from the request

Source: framework/core/Route.php:127

Route::bind()

public static function bind()

Binding the route variables

Source: framework/core/Route.php:198

Route::execute()

public static function execute()

Executing the routing

Source: framework/core/Route.php:215

Route::resolveController()

public static function resolveController($name)

Resolves the controller part of a 'Controller@action' route to a declared class name

• fully qualified names are accepted, with or without a leading backslash: 'Shop\OrderController', '\Shop\OrderController'
• a declared class always wins (a project's own global AIController is used as is)
• a short name that is not a declared class falls back to the framework example controllers namespace (Caligrafy\Controllers), so routes written before 1.6 such as 'AIController@query' keep working

Parameters

• $name string: defines the controller part of the route

Returns string|null: the class name, or null when no such controller exists

Source: framework/core/Route.php:263

Route::get()

public static function get($route, $method = null)

GET http method handler

Parameters

• $route string: defines the uri
• $method object, default null: defines the method to be used, it could be a String or a callback function

Source: framework/core/Route.php:283

Route::post()

public static function post($route, $method = null)

POST http method handler

Parameters

• $route string: defines the uri
• $method object, default null: defines the method to be used, it could be a String or a callback function

Source: framework/core/Route.php:294

Route::put()

public static function put($route, $method = null)

PUT http method handler

Parameters

• $route string: defines the uri
• $method object, default null: defines the method to be used, it could be a String or a callback function

Source: framework/core/Route.php:305

Route::delete()

public static function delete($route, $method = null)

DELETE http method handler

Parameters

• $route string: defines the uri
• $method object, default null: defines the method to be used, it could be a String or a callback function

Source: framework/core/Route.php:316

Route::capability()

public static function capability($method, $route, $name)

Maps a route to a capability (REST): Route::capability('POST', '/books', 'create_book') The route variables ({id}) become inputs of the capability. See Caligrafy\Rest for the request and response format.

Parameters

• $method string: GET, POST, PUT or DELETE
• $route string: the uri
• $name string: the capability name

Source: framework/core/Route.php:329

Route::page()

public static function page($route, $view, array $options = array())

A page: renders a view through the framework's page controller, which gives every page who is signed in and, optionally, an access rule and data from capabilities (pages never read models):

Route::page('/books', 'Books/index');
Route::page('/books/{id}', 'Books/show', ['data' => ['book' => 'get_book']]);
Route::page('/admin/books', 'Books/admin', ['level' => 1, 'data' => ['books' => 'list_books']]);

Options: 'signedIn' (bool), 'level' (int), 'data' (name => read-only capability, or [capability, inputs]), 'with' (fixed values), 'notFound' (a view shown with a 404 when a data capability finds nothing); 2.20.0: 'visitorsOnly' (a path: signed-in people are sent there), 'comeBack' (true: a visitor goes to /login?return=<this page>), 'query' (the names of the query string the view gets)

Parameters

• $route string: the uri
• $view string: the view, as for view()
• $options array, default array(): see PageController::render()

Source: framework/core/Route.php:352

Route::pages()

public static function pages()

The pages declared with Route::page (2.24.0): each with its route, its view and its options (its data capabilities), so that a capability can be shown through the page designed for it

Returns array: of ['route' => 'books/{id}', 'view' => 'Bookshelf/book', 'options' => [...]]

Source: framework/core/Route.php:363

Route::action()

public static function action($route, $capability, array $options = array())

A request answered by a web-only capability (2.21.0, Caligrafy\Action): for what Route::page and Route::form cannot say, such as a sign-in between two sites, a gate or a payment page. The capability is declared #[Capability(..., webOnly: true)] and may return a Caligrafy\Web.

Route::action('/connect', 'cloud_connect');
Route::action('/unlock/{name}', 'unlock_app', ['method' => 'POST']);

Options: 'method' ('GET' by default, 'POST', 'PUT', 'DELETE' or a list), 'signedIn', 'level', 'comeBack', 'visitorsOnly' (as Route::page), 'back', 'error' and 'signIn' (as Route::form, for a refusal it does not answer)

Parameters

• $route
• $capability
• $options array, default array()

Source: framework/core/Route.php:377

Route::bots()

public static function bots()

The data routes of the Watson bot apps (2.21.0): the addresses public/<app> of a bot calls

Source: framework/core/Route.php:391

Route::capabilities()

public static function capabilities($prefix = '/capabilities')

Exposes every capability under a prefix: GET {prefix} lists what the caller may call (with the input schemas), POST {prefix}/{name} calls one. The JS client of the Vue apps and the SPA (php caligrafer.php client) uses it.

Parameters

• $prefix string, default '/capabilities': the uri prefix

Source: framework/core/Route.php:403

Route::notifications()

public static function notifications()

The two pages notification emails link to (2.15.0, Notify): /notify/confirm/{token} confirms an address, /notify/unsubscribe turns the user's emails off from a signed link, also as the one-click POST of mail providers (List-Unsubscribe-Post: the signature replaces the CSRF token). Each answers a short page

Source: framework/core/Route.php:418

Route::snap()

public static function snap(array $options = array())

Snap Cards and the assistant (2.23.0, Caligrafy\Snap): every capability of the app as a card, and an assistant that answers with them, in one line of web.php:

Route::snap();
Route::snap(['assistant' => '/help', 'cards' => '/cards']);

It declares, for the signed-in person:

/assistant              Home (what needs you, insights, things to browse, shortcuts) and the task space
/assistant/ask          what they typed, said, attached or clicked (snap_ask)
/assistant/noticed      what the assistant noticed, and their routines (a settings page)
/snap                   every card they may use (a gallery), /snap/c/{capability} one card at its own address
/snap/run, /snap/call/  a card sent (snap_run), and the snap_* capabilities the pages call

The tables come with php caligrafer.php platform install; card hints are in application/config/snap.php; the assistant uses Claude when ANTHROPIC_API_KEY is set (else it answers from the cards' names, without a model). Changes only ever run from a Confirm the person clicks (Caligrafy\Snap\Consent).

Parameters

• $options array, default array(): 'assistant' (the path of the assistant, '/assistant'), 'cards' (the path of the cards, '/snap')

Source: framework/core/Route.php:448

Route::mcp()

public static function mcp($route = '/mcp')

Exposes the capabilities to AI agents over MCP (Streamable HTTP) at a uri: Route::mcp('/mcp') Agents authenticate with a personal access token and see the capabilities its scopes allow.

Parameters

• $route string, default '/mcp': the uri of the MCP endpoint

Source: framework/core/Route.php:490

Route::form()

public static function form($route, $capability, array $options = array())

A form without a controller (2.19.0, Caligrafy\Form): the form's POST calls a capability, then redirects

Route::page('/books/new', 'Books/new');
Route::form('/books', 'create_book', ['success' => '/books/{id}', 'flash' => 'Book added']);
Route::form('/books/{id}', 'update_book', ['method' => 'PUT', 'success' => '/books/{id}']);

GET stays a Route::page. Options: 'method' (POST, PUT or DELETE, or a list; default POST), 'success' (a path with {placeholders} from the result and the route, or a callable($result) returning one; default back), 'flash' (a message for flash('success'), or [key => message]), 'back' (where invalid input goes; default the Referer of this site), 'error' (the message for flash('error') instead of the capability's), 'signIn' (default /login); 2.20.0: 'visitorsOnly' (a path: signed-in people are sent there), 'same' ([field => [other field, message]]), 'accepted' ([field => message]: a box that must be ticked), 'inputs' (values only the server sets: an array or a callable($input)), 'signsIn' (the field of the answer that holds the id of the person to sign in), 'signsInWith' (how: 'password' by default, what AuthRoutes::signedInBy() answers). 'success' may be a full address, or a callable returning one (a payment page). Invalid input goes back with errors($field), old($field) and flash('error') for the next page. JSON requests get the REST answer.

Parameters

• $route
• $capability
• $options array, default array()

Source: framework/core/Route.php:515

Route::auth()

public static function auth(array $options = array())

The sign-in pages without a controller (2.19.0, Caligrafy\AuthRoutes): /login, /logout, /register, /notAuthorized and, with 'passkeys' => true, the passkey endpoints. Needs Auth::authentication(...) before it.

Route::auth(['home' => '/books']);

Options: prefix, home ('/'), logout ('/'), register (true, false or the capability), attempts (5), lock (900 seconds), views, passkeys (false), identifier ('username', or the users column people sign in with: 'email'), signInAfterRegister (false: true signs the new account in and goes 'home'). See AuthRoutes.

Parameters

• $options array, default array()

Source: framework/core/Route.php:534

Route::webhook()

public static function webhook($route, $capability, array $options = array())

Events another service posts (2.19.0, Caligrafy\Webhook): POST only, no CSRF token, the signature checked

Route::webhook('/stripe/events', 'record_payment', ['verify' => 'stripe', 'secret_env' => 'STRIPE_WEBHOOK_SECRET']);
Route::webhook('/hooks/github', 'record_push', ['verify' => fn ($raw, $headers) => hash_equals(...)]);

The capability gets ['event' => the decoded JSON body] as the system (Context::system('webhook', $path)).

Parameters

• $route
• $capability
• $options array, default array()

Source: framework/core/Route.php:545

Route::download()

public static function download($route, $capability, array $options = array())

A read-only capability's result as a file (2.19.0, Caligrafy\Download): GET

Route::download('/books.csv', 'list_books', ['as' => 'csv', 'filename' => 'books.csv']);
Route::download('/photos.zip', 'list_photo_files', ['as' => 'zip', 'root' => 'public/uploads/photos']);  // 2.22.0

Options: 'as' (csv, json or zip: the files the capability lists, under 'root', default public/uploads), 'columns' (2.19.5: the header row, written even with no row), 'filename' (a name or a callable($result, $input)), 'bom' (bool), 'formulas' (keep cells that start with = + - @ as they are), 'signIn'. Refusals as Route::page; inputs to fix answer 422 (2.19.5).

Parameters

• $route
• $capability
• $options array, default array()

Source: framework/core/Route.php:563

Route::redirect()

public static function redirect($from, $to, $status = 302, array $options = array())

A GET that sends the visitor elsewhere (2.19.0): no closure, no controller

Route::redirect('/', '/books');
Route::redirect('/old/books/{id}', '/books/{id}', 301);

{name} in $to takes the route variable of $from (url-encoded). $to is a path of this site or a full http(s) address.

Parameters

• $from
• $to
• $status int, default 302: 301, 302 (default), 303, 307 or 308
• $options array, default array(): 'keepQuery' (2.20.0, true: the query string of the request goes along)

Source: framework/core/Route.php:578

Route::withQuery()

public static function withQuery($target, array $query)

An address with a query string added (2.20.0, 'keepQuery'); the server's rewrite adds 'uri', which never goes along

Parameters

• $target
• $query array

Source: framework/core/Route.php:601

Route::redirectTarget()

public static function redirectTarget($to, array $variables = array())

Where a Route::redirect sends: $to with its {placeholders} filled from the route variables (url-encoded)

Parameters

• $to
• $variables array, default array()

Source: framework/core/Route.php:618

Route::isWebhook()

public static function isWebhook($uri)

Whether a uri is the address of a Route::webhook (no CSRF token: its signature is checked)

Parameters

• $uri

Source: framework/core/Route.php:626

Route::isMcp()

public static function isMcp($uri)

Whether a uri is an MCP endpoint (Route::mcp): Request skips the session CSRF check for its POST, since Mcp\Http answers 401 to a request without a personal access token and never uses the session (2.19.1)

Parameters

• $uri

Source: framework/core/Route.php:641

Route::routes()

public static function routes()

The routes declared so far: [['method' => 'GET', 'route' => 'books/{id}'], ...]

Source: framework/core/Route.php:655

Route::reset()

public static function reset()

Forgets every route (tests)

Source: framework/core/Route.php:667

Route::handler()

public static function handler($method, $route)

The closure (or Controller@action) of a declared route, without a request (tests): Route::handler('POST', '/books')

Parameters

• $method
• $route

Source: framework/core/Route.php:676