Repository navigation
Query Builder Pagination
paginate() gives one page of a query's rows with the
numbers a page needs: the rows, how many there are in all, which page it is and how many pages there are. It runs two
queries (a count, then the page), and one when the page is past the last. A capability that returns a page serves it
the same way to web pages, REST, the JS client, agents and Snap's lists. Since 2.19.0.
$page = Book::query()->orderBy('title')->paginate(2, 2);
// ['data' => [Kindred, Parable of the Sower], 'total' => 5, 'page' => 2, 'per_page' => 2, 'pages' => 3]/caligrafy-quill:new-capability list_books books:read read-only: the books sorted by title, 20 per page, with their author
Claude writes paginate(20, $input['page'] ?? 1) with 'page' => 'integer' in $rules.
Check before you say OK: php caligrafer.php call list_books page=2 gives "page": 2 (and "data": [] when there
are fewer than 21 books).
-
The capability pages with the page of its input: REST, an agent and the command line have no query string.
public $rules = array('author_id' => 'integer', 'page' => 'integer'); public $descriptions = array( 'author_id' => 'Optional: only the books of this author', 'page' => 'Optional: the page, 1 by default (20 books per page)' ); public function handle(array $input, Context $context) { $query = Book::with('author')->orderBy('title'); if (!empty($input['author_id'])) { $query->where('author_id', $input['author_id']); } return $query->paginate(20, $input['page'] ?? 1); }
-
The page, in
application/config/routing/web.php: the query string reaches the capability as its inputs (?page=2,?author_id=2), and thequeryoption gives the view$author_idto keep in the links:Route::page('/books', 'Bookshelf/books', ['data' => ['books' => 'list_books', 'authors' => 'list_authors'], 'query' => ['author_id']]);
-
The links, in
application/views/Bookshelf/books.pug(the whole view):The rows are//- the next and previous pages keep the author of the address (?author_id=2) - $filter = $author_id !== '' ? '&author_id=' . (int) $author_id : ''; p.cq-auth-note | Page #{$books['page']} of #{$books['pages']}, #{$books['total']} books if $books['page'] > 1 | · a(href="{$home}books?page=" . ($books['page'] - 1) . $filter) Previous if $books['page'] < $books['pages'] | · a(href="{$home}books?page=" . ($books['page'] + 1) . $filter) Next
$books['data']. Pug in Caligrafy is PHP: strings join with..
paginate($perPage = 20, $page = null)
returns:
| Key | What it is |
|---|---|
data |
the rows of the page (arrays or models, with their relations) |
total |
the rows of the whole query |
page |
the page number used |
per_page |
the rows per page |
pages |
the number of pages, at least 1 |
-
Without a page number,
paginate()readspagefrominput($array)when you gave one, else from the query string (?page=2). - A page number that is not a whole number >= 1 is page 1. A page past the last one gives
'data' => []and runs no second query. -
$perPagemust be a whole number >= 1: anything else throwspaginate() needs a number of rows per page >= 1. - Elsewhere a page keeps its shape:
Route::downloadexports the rows of that page only; a Snap Show: List shows its pages; a card view gets$rowsand$page.
-
paginate(20)in a capability: it reads the query string, which REST, agents and the command line do not send. Writepaginate(20, $input['page'] ?? 1)with'page' => 'integer'in$rules. -
pagemissing from$rules: undeclared inputs never reachhandle(), so every page is page 1. -
Reading
$_GETin the view: the view gets the query string only through thequeryoption ofRoute::page.
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)