Repository navigation
Route Download
Route::download($route, $capability, $options) answers a GET with the result of a read-only capability as a
file: a CSV, a JSON file, or the files it lists in one ZIP. The capability stays plain data, so the same list also
reaches REST, the JS client and agents. Since 2.19.0; columns since 2.19.5, ZIP since 2.22.0.
Route::download('/authors.csv', 'list_authors', ['filename' => 'authors.csv']);
Route::download('/books.json', 'list_books', ['as' => 'json']); // a page of list_books, ?page=2 for the next
Route::download('/photos.zip', 'list_photo_files', ['as' => 'zip', 'root' => 'public/uploads/photos']);"Let people export the authors as CSV from a link on the authors page."
Check before you say OK:
- the route names a read-only capability;
- the export returns arrays with the columns it means to show (not models: they carry every property);
- a ZIP's
rootis the folder that holds the files, relative to the project.
A step-by-step CSV export: How to export a list as CSV.
| Option | Default | What it does |
|---|---|---|
as |
'csv' |
'csv', 'json' (pretty-printed) or 'zip' (the files the capability lists, 2.22.0); anything else stops with an error when web.php runs |
root |
'public/uploads' |
for zip: the folder of the project the files are read from; a file outside it is never sent. A root with .. stops with an error when web.php runs |
columns |
the first row's keys | the header row and its order, written even when there is no row: ['title', 'year'] (2.19.5) |
filename |
<capability>.<as> |
a name, or function ($result, $input) { return 'books-' . date('Y-m-d') . '.csv'; }
|
bom |
false |
true starts the CSV with a UTF-8 BOM (Excel) |
formulas |
false |
true keeps cells that start with =, +, -, @ as they are |
signIn |
'/login' |
where a visitor goes when the capability needs someone |
- The capability must be read-only: opening a link must not change data.
- It gets the query string and the route variables (
/books.csv?author_id=2) as the person who opens the link; the route variables win. - Refusals are those of
Route::page: a visitor goes to sign in,forbiddenis403, nothing found is404. An input to fix (?author_id=abc) answers422with the capability's error as JSON, as REST does (2.19.5; before,404). - The answer carries
Cache-Control: private, no-storeandX-Content-Type-Options: nosniff.
- The header row comes from
columns, else from the first row's keys (then an empty result is an empty file). - Values are quoted where needed (RFC 4180, lines end with CRLF), UTF-8.
- A text cell that starts with
=,+,-,@or a tab gets a'first, so a spreadsheet does not run it as a formula (formulasturns that off). - Arrays in a cell are written as JSON, booleans as
true/false. A related row (with('author')) is one cell, in JSON. - Each row of the list is a line. A
paginate()page exports that page only: returnget()to export every row; a single record gives one line. -
The columns are the keys of the first row. A model carries every one of its properties:
Book::query()->select('id', 'title')->get()exportsid,titleand every other column ofBook, empty. Return arrays for a narrow export:Database::table('books')->select('id', 'title')->get()orBook::query()->select('id', 'title')->arrays()->get().
The capability lists the files; Route::download puts them in one archive and sends it.
#[Capability(name: 'list_photo_files', description: 'The files of the photos, oldest first', scope: 'photos:read', level: 1, readOnly: true)]
class ListPhotoFiles extends Service
{
public function handle(array $input, Context $context)
{
return array_map(fn ($photo) => [
'file' => $photo['image'], // relative to 'root'
'name' => 'pictures/' . date('Y-m-d_H-i-s', strtotime($photo['created_at'])) . '.jpg', // in the archive
], Photo::query()->arrays()->select('image', 'created_at')->orderBy('created_at')->get());
}
}Route::download('/photos.zip', 'list_photo_files', ['as' => 'zip', 'root' => 'public/uploads/photos',
'filename' => fn ($files, $input) => 'photos-' . date('Y-m-d') . '.zip']);-
Each item is a path (the file keeps its own name) or
['file' => path, 'name' => 'folder/name.jpg']. Paths are relative toroot; apaginate()page gives its rows. -
Only files under
rootgo in. A path that leaves it (../../.env), a folder, or a missing file is left out without an error. Names are cleaned (no.., no leading/), and a name used twice becomesname (2).jpg. -
No file at all answers
404. Hide the link when there is nothing to download, or throwServiceError::notFound('No photo yet')in the capability. - Images, video, audio and archives are stored as they are; other files are compressed. The archive is written to a
temporary file, sent with its
Content-Length, then removed. - It needs PHP's zip extension: Caligrafy's Docker images and Caligrafy Cloud have it.
- In a test,
Download::archive($files, ['root' => ...])builds the same archive (['path', 'count', 'names']; removepathafterwards).
-
A download of a capability that writes:
Route::downloadrefuses it when the link is opened. - A model query for a narrow export: every column of the model is in the file. Return arrays.
-
A ZIP whose files live outside
root: they are left out, and an empty list answers404. Give the folder that holds them, relative to the project (public/uploads/photos), and paths relative to it. -
A web-only capability that streams its own ZIP (before 2.22.0): return the list and use
'as' => 'zip'.
- How to export a list as CSV
-
Queries:
select(),arrays(),paginate() -
Pages:
Route::page: the same refusals - Declarative routes
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)