Repository navigation
Route Action
Route::page shows a view and Route::form calls a capability and redirects. A few requests are neither: a sign-in
between two sites, a page that chooses between a view and a redirect, a gate, a page that creates a payment. Since
2.21.0 they are capabilities too, declared webOnly: true and served by one line, Route::action($route, $capability, $options). This is what replaces the controller of a new application.
Route::action('/authors/{author_id}/books', 'open_author_books', ['back' => '/books']);"Add GET /authors/{author_id}/books: when the author has exactly one book, go straight to that book's page;
otherwise show the list."
Check before you say OK:
-
webOnly: trueis on a capability that needs the session, signs someone in, or chooses between a page and a redirect; everything else stays a plain capability, so REST and agents can reach it; - the web-only capability calls the plain ones with
$this->capability(); - no controller and no closure was written.
-
The capability. Run
docker compose exec dev-box php caligrafer.php service Bookshelf/OpenAuthorBooksand makeapplication/services/Bookshelf/OpenAuthorBooks.phpread:<?php use Caligrafy\Capability; use Caligrafy\Context; use Caligrafy\Service; use Caligrafy\Web; // open_author_books: one book goes straight to its page, otherwise the list #[Capability( name: 'open_author_books', description: 'Opens the books of an author: the book itself when there is one, otherwise the list.', readOnly: true, public: true, webOnly: true )] class OpenAuthorBooks extends Service { public $rules = array('author_id' => 'required|integer'); public function handle(array $input, Context $context) { $books = $this->capability('list_books', array('author_id' => $input['author_id']), $context); if ($books['total'] == 1) { return Web::redirect('/books/' . $books['data'][0]['id']); } return Web::view('Bookshelf/books', array('books' => $books)); } }
-
The route. In
web.php:Route::action('/authors/{author_id}/books', 'open_author_books', ['back' => '/books']);
-
Try it.
curl -s -i http://localhost:8080/authors/3/books | grep -iE "^HTTP|^Location" curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/authors/2/books curl -s -i http://localhost:8080/authors/abc/books | grep -iE "^HTTP|^Location"
They print
302to/books/5(one book),200(a list of two), and302to/books(thebackoption), whereflash('error')says "Some of the inputs are invalid".docker compose exec dev-box php caligrafer.php call open_author_books author_id=3prints{"error":{"code":"not_found","message":"There is no capability 'open_author_books'"}}: only the route reaches it.
Route::action('/unlock/{name}', 'unlock_shelf', ['method' => 'POST']);
Route::action('/shelf/report', 'shelf_report', ['level' => 1, 'comeBack' => true]);| Option | Default | What it does |
|---|---|---|
method |
'GET' |
'POST', 'PUT', 'DELETE', or a list (['GET', 'POST']) |
signedIn, level
|
none | as in Route::page: visitors go to /login, people below the level to /notAuthorized
|
comeBack |
false |
with signedIn or level, or when the capability needs someone: visitors go to /login?return=<this page>
|
visitorsOnly |
none | a path: people already signed in are sent there |
back |
the Referer of this site, else /
|
where invalid input or a conflict goes, with the route's {placeholders}
|
error |
the capability's message | your message for flash('error')
|
signIn |
'/login' |
where a visitor goes when the capability needs someone (comeBack replaces it) |
| The capability returns | The browser gets |
|---|---|
Web::view('Bookshelf/book', $data, $status = 200) |
a Pug view, with $authorized and $user as on Route::page ($data wins). A request that asks for JSON gets the data as JSON |
Web::redirect('/books', $status = 302) |
a redirect: a path of this site or a full http(s) address |
Web::json($data, $status = 200) |
JSON, the data as it is, with no {"data": ...} around it |
Web::text($body, $status = 200) |
the text as it is |
any of them ->header('Cache-Control', 'no-store')
|
one more response header |
| plain data (an array, a model) | JSON, as with Web::json
|
When it refuses. A capability that answers a refusal itself returns a Web. One that throws a ServiceError gets
the answers of Route::form:
| It throws | A browser | A JSON request |
|---|---|---|
invalid or conflict
|
back (back, the Referer, or /) with errors(), old(), flash('error')
|
422 or 409 and the REST error |
unauthenticated |
the sign-in page (comeBack: and back here) |
401 |
forbidden |
403 [ERROR 1006]
|
403 |
not_found or anything else |
404 [ERROR 1005]
|
404 |
What it receives. The inputs its $rules declare, from the form, the JSON body or the query string, and the route
variables, which win (/books/3?id=9 gives id = 3, 2.21.2). Its files are saved and given as URLs, as for
Route::form. It runs as the person who sent the request, with its public, scope and level checks, its
validation and its audit log, like any capability.
Only capabilities touch models: a web-only capability is a capability. What sets it apart is what it may do besides:
| A plain capability | A web-only capability |
|---|---|
| returns data, or refuses | may also return a view, a redirect, JSON or text |
never reads the session or the request: $context says who calls |
may read session(), request(), $_SERVER, $_COOKIE
|
| never signs anyone in | may sign people in and out |
on a page, only readOnly
|
a GET may change data |
reached by REST, MCP, the JS client, the command line, Route::page, Route::form, $this->call()
|
reached by Route::action only
|
Everywhere else it answers not_found "There is no capability", and it is left out of GET /capabilities, MCP,
php caligrafer.php capabilities and php caligrafer.php client. So keep the work several channels share in plain
capabilities, and call them from the web-only one:
$books = $this->capability('list_books', array('author_id' => 2), $context); // as the same person, with its rules-
A page that leaves or reloads:
Caligrafy\AuthRoutes::signIn($user, null, 'partner')gives a new session id, a new CSRF token, and records how the session signed in (the third argument, 2.21.3, read byAuthRoutes::signedInBy()). -
A page that stays open and keeps sending JSON:
session_regenerate_id(true); Auth::authorize($user); AuthRoutes::rememberSignIn('face');. The page keeps its token. -
$contextwas built before the sign-in and does not change: to call a capability as the person just signed in, build a new one withContext::fromRequest(request(), 'web').
A complete sign-in through another site is in Authentication.
- A form's
POST,PUTorDELETEneeds its_token(=csrf()):403[ERROR 3000]without it. - A JSON call (
Accept: application/json),GETincluded, needs the page'sX-CSRF-Tokenheader (apiHeaders()of the Vue apps) or, withAuth::activateAPI();inweb.php, a token that grants everything (--scopes "*"), signed in or not:401[ERROR 1004]without it (2.21.1). A scoped token is refused: programs use the capability routes. - A plain
GETopened by a link has no token, and can be triggered by a link on another site: keep aGETthat changes data to what is harmless when that happens, and use'method' => 'POST'with a form for the rest.
Tests. $this->action('open_author_books', ['author_id' => 3], $user) calls it as Route::action does and returns
what it answered; ->describe() gives type, target, data, status and headers. $this->call() answers
not_found, as every other channel does. See Testing your app.
Route::action()-
Caligrafy\ActionandCaligrafy\Web -
AuthRoutes::signIn(),AuthRoutes::rememberSignIn() Context::fromRequest()
-
Route::actionon a capability withoutwebOnly: true, orwebOnly: truebehindRoute::page,Route::formor REST: the first stops with an error that names it, the others answer "There is no capability". -
A web-only capability for work other channels need: agents and programs cannot reach it. Put the work in a plain
capability and call it with
$this->capability(). -
A JSON call without
X-CSRF-Token:401[ERROR 1004], even for aGETand for a visitor. SendapiHeaders(). -
AuthRoutes::signIn()on a page that stays open: it gives the session a new CSRF token, and the page's next JSON call answers401. Usesession_regenerate_id(true); Auth::authorize($user);there. -
Calling a capability as the person just signed in with the old
$context: it still says who called before. Build a new one withContext::fromRequest(request(), 'web').
- How to move a controller route to a declared route
- Request: what a web-only capability reads from the request
- Authentication: a sign-in through another site
- Declarative routes
- Release notes 2.21.0
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)