StaticFiles class final

A public directory served under a URL prefix (ApplicationBuilder .withStatic('public', prefix: '/assets')), traversal-proof by construction: the directory is scanned at boot and a request is answered by looking its path up among the files found. No part of the URL reaches the file system, so .., %2e%2e, backslashes or a symbolic link planted later can only miss the lookup.

Dot files (.env, .git, .vite) and symbolic links are skipped: a link such as public/storage (storage:link) leads to uploads, which change at run time and are served by their disk instead.

A URL from url carries the file's version (?v=<sha256 prefix>) and is answered with Cache-Control: public, max-age=31536000, immutable; without it, or with a stale one, the answer may be cached for maxAge only. Files a Vite build names by content hash are immutable either way.

Constructors

StaticFiles(String directory, {String prefix = '/assets', Duration maxAge = const Duration(minutes: 5), bool rescan = false, String buildDirectory = 'build'})
The files under directory (absolute), served under prefix.

Properties

buildDirectory → String
Vite's output directory under directory (public/build), where manifest.json maps sources to built files (Laravel's layout).
final
directory → String
The absolute directory.
final
hashCode → int
The hash code for this object.
no setterinherited
maxAge → Duration
How long a response without the current version may be cached.
final
paths → List<String>
The paths found, sorted.
no setter
prefix → String
The URL prefix, without a trailing slash ('' for the root).
final
rescan → bool
Development mode (APP_ENV=local by default): a miss scans the directory again (at most once a second) and a changed file gets a new version, so new and edited files show up without a restart.
final
route → String
The route pattern serving the directory (/assets/{path*}).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

has(String path) → bool
Whether path (under the directory) was found.
manifest() → Map<String, Object?>
The versions as dartisan static:hash writes them.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
scan({bool useManifest = true}) → void
Scans the directory and versions every file. A manifest written by dartisan static:hash supplies the versions of files whose size and modification time it recorded, so a production boot reads no file; useManifest false hashes everything.
serve(Request request, String path) → Future<Response>
Answers request for path, the part of the URL after prefix: 404 unless the scan found exactly that path.
toString() → String
A string representation of this object.
inherited
url(String path) → String
The URL of path with its version (Laravel's asset() with a cache-busting query): /assets/neo.css?v=1a2b3c4d5e6f. A file of the Vite manifest (resources/js/app.js) gives its built file; any other path its plain URL, as asset() does not check that a file exists.
version(String path) → String?
The current version of path, or null when it was not found.
viteUrl(String entry) → String?
The URL of the file Vite built from entry (Vite::asset()), or null when the manifest does not list it.
writeManifest() → String
Hashes every file again and writes manifestName; returns its path.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

immutable → const String
The Cache-Control of a request carrying the current version.
manifestName → const String
The name of the version manifest dartisan static:hash writes in the directory; a dot file, so it is never served.
versionLength → const int
How many hex digits of the SHA-256 a version keeps.