Asset Management

Zap's Zap\Core\Utils\Assets service loads registered CSS and JavaScript files into a page. Register asset nicknames and their local file names, CDN URLs, and optional defaults in config/css.php and config/js.php. Controllers choose which nicknames a page needs and whether to prefer local files or CDN URLs.

Asset loading is separate from Vite. Use the asset registry for prebuilt files placed in the framework's assets directories or served from a CDN. For Vite source entrypoints and manifest-based builds, see the Vite guide.

Register assets

Each key is the nickname used by a controller. CSS records provide local, cdn, and optional default values. JavaScript records also specify the script type and extra HTML attributes.

// config/css.php
return [
 'site' => [
 'local' => 'site.css',
 'cdn' => 'https://cdn.example.com/site.css',
 'default' => 'none',
 ],
];

// config/js.php
return [
 'site' => [
 'local' => 'site.js',
 'cdn' => 'https://cdn.example.com/site.js',
 'default' => 'none',
 'type' => 'text/javascript',
 'attributes' => 'defer',
 ],
];

For local assets, put CSS files in public/assets/css and JavaScript files in public/assets/js. With DEV_SERVER=NATIVE, the generated URLs use /assets/css/ and /assets/js/; other values use /public/assets/css/ and /public/assets/js/. Set an unavailable local or CDN option to the string none.

Load assets in a page

Use setAssets() in the controller and pass its result to the view as assets. The base layout loads CSS and header JavaScript in the document head, then footer JavaScript before the closing body tag.

$data = [
 'assets' => $this->assets->setAssets(
 source: 'local',
 header_css: ['site'],
 header_js: [],
 footer_js: ['site']
 ),
];

$html = $this->render('pages/home', $data);

The asset lists contain registered nicknames, not file paths. You can request the same nickname on different pages and give each page only the assets it needs.

Choose local files or CDN

Pass source: 'local' to prefer each asset's local file. If that asset's local value is none, the service uses its CDN URL when one is configured. For any source other than local, the service uses the CDN URL; if that URL is none, the asset is not emitted.

Unregistered nicknames are skipped. CSS is rendered as a stylesheet link. JavaScript is rendered as a script tag using the registered type and attributes.

Default assets

Set default to header in a CSS registration or to header/footer in a JavaScript registration to include it on every page that calls setAssets(). The method adds these defaults to the page's explicit lists and removes duplicate nicknames. Entries without a recognized placement are not automatically loaded.

// Example CSS default
'bootstrap' => [
 'local' => 'bootstrap.min.css',
 'cdn' => 'https://cdn.example.com/bootstrap.min.css',
 'default' => 'header',
],

Choose defaults for files that are genuinely needed site-wide; add page-specific files through the named arguments to setAssets().