Repository navigation
Web Only Capabilities
A web-only capability is a capability declared webOnly: true. It is for a request that belongs to the browser: a
sign-in between two sites, a page that chooses between a view and a redirect, a gate, a page that creates a payment.
It keeps everything a capability has (its checks, its validation, its audit) and may do what a plain capability never
does: answer with a view or a redirect, read the session, sign people in. The price: Route::action is the only way to
it. Since 2.21.0.
This page is about the capability. The route that serves it, its options and how it answers are on
Route::action.
/caligrafy-quill:new-capability open_author_books web-only public: open the books of an author, the book itself when there is only one
Claude writes the capability with webOnly: true, keeps the shared work in plain capabilities that it calls with
$this->capability(), and adds the Route::action line to web.php.
Check before you say OK:
-
php caligrafer.php capabilitiesdoes not list it (web-only capabilities are left out); - the plain capabilities it calls are listed, so agents and programs can still do the work;
- a test calls it with
$this->action().
php caligrafer.php service Bookshelf/OpenAuthorBooks writes the class; the command has no flag for web-only, so add
webOnly: true to the attribute:
<?php
use Caligrafy\Capability;
use Caligrafy\Context;
use Caligrafy\Service;
use Caligrafy\Web;
#[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));
}
}and serve it in application/config/routing/web.php, before Route::run();:
Route::action('/authors/{author_id}/books', 'open_author_books', ['back' => '/books']);The rule of the framework still holds: 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 (Caligrafy\Web) |
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
|
What it answers:
| It returns | The browser gets |
|---|---|
Web::view('Bookshelf/book', $data, $status = 200) |
a Pug view, with $authorized and $user as on Route::page
|
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 |
Web::text($body, $status = 200) |
the text as it is |
any of them ->header('Cache-Control', 'no-store')
|
one more response header |
| plain data | JSON |
Capabilities::call() answers not_found There is no capability '<name>' to any context that does not come from
Route::action ($context->viaAction). So REST, MCP, the JS client, php caligrafer.php call, Route::page,
Route::form, Route::download and a controller's $this->call() cannot reach it, and it is left out of
GET /capabilities, MCP tools/list, php caligrafer.php capabilities and the generated JS client.
Keep the work several channels share in plain capabilities, and call them from the web-only one, as the same person:
$books = $this->capability('list_books', array('author_id' => 2), $context); // its checks, validation and audit- For a page that leaves or reloads:
Caligrafy\AuthRoutes::signIn($user, null, 'partner'): a new session id, a new CSRF token and how it signed in (the third argument, 2.21.3, read byAuthRoutes::signedInBy()). - For 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 whole example, a sign-in through another site, is on Authentication.
$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 (Testing your app).
Reference: Caligrafy\Web,
Caligrafy\Action,
AuthRoutes::signIn().
-
webOnly: trueon a feature agents or programs need (G143): they get "There is no capability". Keep the work in a plain capability and let the web-only one call it with$this->capability(). -
Reading the session in a plain capability (G52): only a web-only capability may; the others read
$context. -
Snap's own
snap_askandsnap_runin a test (G158): they are web-only, so call them with$this->action().
-
Route::action: the route, its options, CSRF and JSON - Declarative routes
- The capability attribute · The context
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)