PHPackages webrouse/n-asset-macro - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Templating & Views](/categories/templating) 4. / 5. webrouse/n-asset-macro ActiveLibrary[Templating & Views](/categories/templating) webrouse/n-asset-macro ====================== Asset macro for Latte and Nette Framework useful for assets cache busting (with gulp, webpack, etc.) v2.0.2(7y ago)1264.4k1[1 issues](https://github.com/webrouse/n-asset-macro/issues)1MITPHPPHP >=7.1 Since Jan 20Pushed 7y ago2 watchersCompare [ Source](https://github.com/webrouse/n-asset-macro)[ Packagist](https://packagist.org/packages/webrouse/n-asset-macro)[ RSS](/packages/webrouse-n-asset-macro/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (9)Dependencies (12)Versions (10)Used By (1) Webrouse/n-asset-macro ====================== [](#webrousen-asset-macro) [![Build Status](https://camo.githubusercontent.com/205071b8615d8f12b10ea293500b8e1808a10a858b4c80d1abbec9bd5851c2bf/68747470733a2f2f7472617669732d63692e6f72672f776562726f7573652f6e2d61737365742d6d6163726f2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/webrouse/n-asset-macro)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/76d63de4a3f713f2dcb83f84bbdcd6f1a2c4141b7f81ec7214aacada32a75d18/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f776562726f7573652f6e2d61737365742d6d6163726f2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/webrouse/n-asset-macro/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/f7f11124ae69ffa9d6fb97d26d80c9c4562b703a93e42b6c95cf0840b9d006c7/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f776562726f7573652f6e2d61737365742d6d6163726f2f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/webrouse/n-asset-macro/?branch=master)[![Latest stable](https://camo.githubusercontent.com/badec9fb936ce93c8b0503b574b95a9f8fff471725999074cf4d71bf307bac74/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f776562726f7573652f6e2d61737365742d6d6163726f2e737667)](https://packagist.org/packages/webrouse/n-asset-macro)[![Donate](https://camo.githubusercontent.com/604e3db9c8751116b3f765aad0353ec7ded655bbe8aaacbc38d8c4a6b784b3ed/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f6e6174652d50617950616c2d677265656e2e737667)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ZT44VCJ4QEAF4) Asset macro for [Latte](https://latte.nette.org) and [Nette Framework](https://nette.org). Useful for assets [cache busting](https://www.keycdn.com/support/what-is-cache-busting)with [gulp](https://github.com/webrouse/n-asset-macro/tree/master/examples/gulp "Gulp example"), [webpack](https://github.com/webrouse/n-asset-macro/tree/master/examples/webpack "Webpack example") and other similar tools. Requirements ------------ [](#requirements) - [PHP](https://php.net) >=7.1 - [Nette](https://github.com/nette) >=2.4 - [Latte](https://github.com/nette/latte) >=2.4 `Nette 3` is fully supported and tested. Installation ------------ [](#installation) The best way to install **webrouse/n-asset-macro** is using [Composer](http://getcomposer.org/): ``` $ composer require webrouse/n-asset-macro ``` Then register the extension in the config file: ``` # app/config/config.neon extensions: assetMacro: Webrouse\AssetMacro\DI\Extension ``` Usage ----- [](#usage) Macro can by used in any presenter or control template: ``` {* app/presenters/templates/@layout.latte *} ``` It prepends path with `$basePath` or `$baseUrl` (see [absolute](#absolute)) and loads revision from the [revision manifest](#revision-manifest): ``` ``` See the [examples](#examples) for usage with [gulp](https://github.com/webrouse/n-asset-macro/tree/master/examples/gulp "Gulp example"), [webpack](https://github.com/webrouse/n-asset-macro/tree/master/examples/webpack "Webpack example"). Revision manifest ----------------- [](#revision-manifest) **Revision manifest is a JSON file that contains the revision (path or version) of asset.** It can be generated by various asset processors such as [gulp](https://github.com/webrouse/n-asset-macro/tree/master/examples/gulp) and [webpack](https://github.com/webrouse/n-asset-macro/tree/master/examples/webpack), [see examples](#examples). Revision manifest is searched in the asset directory and in the parent directories up to `%wwwDir%`. Expected file names: `assets.json`, `busters.json`, `versions.json`, `manifest.json`, `rev-manifest.json`. **The path to revision manifest can be set directly (instead of autodetection):** ``` # app/config/config.neon assetMacro: manifest: %wwwDir%/assets.json ``` **Or you can specify `asset => revision` pairs in config file:** ``` # app/config/config.neon assetMacro: manifest: 'js/vendor.js': 16016edc74d # or js/vendor.16016edc74d.js 'js/main.js': 4b82916016 # or js/main.4b82916016.js ``` Revision manifest may contains asset version or the asset path. Both ways are supported. ### Method 1: asset version in file name (preferable) [](#method-1-asset-version-in-file-name-preferable) With this method, the files have a **different name at each change**. Example revision manifest: ``` { "js/app.js": "js/app.234a81ab33.js", "js/vendor.js": "js/vendor.d67fbce193.js", "js/locales/en.js": "js/locales/en.d78da025b7.js", "js/locales/sk.js": "js/locales/sk.34edebe2a2.js", "css/app.css": "css/app.04b5ff0b97.js" } ``` With the example manifest, the expr. `{asset "js/app.js"}` generates: `/base/path/js/app.234a81ab33.js`. ### Method 2: asset version as a query string [](#method-2-asset-version-as-a-query-string) This approach looks better at first glance. The **asset path is still the same**, and only the parameter in the query changes. However, it can [cause problems](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/) with some cache servers, which don't take the URL parameters into account. Example revision manifest: ``` { "js/app.js": "234a81ab33", "js/vendor.js": "d67fbce193", "js/locales/en.js": "d78da025b7", "js/locales/sk.js": "34edebe2a2", "css/app.css": "04b5ff0b97" } ``` With the example manifest, the expr. `{asset "js/app.js"}` generates: `/base/path/js/app.js?v=234a81ab33`. Asset macro automatically detects which of these two formats of revision manifest is used. Macro arguments --------------- [](#macro-arguments) ### `format` [](#format) The format is defined by the second macro parameter or using the `format` key (default `%url%`). `format` can be used with `needed => false` to hide whole asset expression (eg. ` true` else `%basePath%``%basePath%``/base/path``%baseUrl%``http://www.example.com/base/path``%url%``%base%%path%` (default format) eg. `/base/path/js/main.8c48f58df.js```` {* app/presenters/templates/@layout.latte *} {asset 'js/vendor.js', ''} ``` ### `needed` [](#needed) Error handling is set in the [configuration](https://github.com/webrouse/n-asset-macro/blob/master/README.md#configuration) using: `missingAsset`, `missingManifest` and `missingRevision` keys. These settings can by overrided by third macro parameter or using `needed` key (default `true`). Argument `needed => false` will cause the missing file or the missing revision record will be ignored. Missing version will be replaced with `unknown` string. **Example of `needed` parameter** - `absent.js` file doesn't exist. - `missing_rev.js` exists but doesn't have revision in manifest (or the manifest has not been found). ``` {asset 'js/absent.js', '', FALSE} {asset 'js/missing_rev.js', format => '', needed => FALSE} ``` Generated output: ``` ``` ### `absolute` [](#absolute) Output URL type - relative or absolute - is defined by fourth macro parameter or using `absolute` key (default `false`). If `absolute => true` or asset path is prefixed with `//` eg. (`//assets/js/main.js`), the absolute URL will be generated instead of a relative URL. ``` {asset 'js/vendor.js'} {* equal to {asset 'js/vendor.js', absolute => false} *} {asset '//js/vendor.js'} {* equal to {asset 'js/vendor.js', absolute => true} *} ``` Generated output: ``` ``` Caching ------- [](#caching) In production mode is the macro output cached in default application's [cache storage](https://doc.nette.org/en/2.4/caching). It can be changed in the [configuration](https://github.com/webrouse/n-asset-macro/blob/master/README.md#configuration) using the boolean `cache` key. Configuration ------------- [](#configuration) Default configuration, which usually doesn't need to be changed: ``` # app/config/config.neon assetMacro: # Cache generated output cache: %productionMode% # Path to revision manifest or asset => revision pairs, # if set, the autodetection is switched off manifest: null # %wwwDir%/assets/manifest.json # File names for automatic detection of revision manifest autodetect: - assets.json - busters.json - versions.json - manifest.json - rev-manifest.json # Absolute path to assets dir assetsPath: %wwwDir%/ # %wwwDir%/assets # Public path to "assetsPath" publicPath: / # /assets # Action if missing asset file: exception, notice, or ignore missingAsset: notice # Action if missing manifest file: exception, notice, or ignore missingManifest: notice # Action if missing asset revision in manifest: exception, notice, or ignore missingRevision: notice # Default format, can be changed in macro using "format => ..." format: '%%url%%' # character % is escaped by %% ``` `ManifestService` ----------------- [](#manifestservice) It is also possible to access the manifest from your code using `Webrouse\AssetMacro\ManifestService` (from DI container). ``` /** @var ManifestService $manifestService */ $cssAssets = $manifestService->getManifest()->getAll('/.*\.css$/'); ``` Examples -------- [](#examples) Examples based on [nette/sandbox](https://github.com/nette/sandbox): - [Gulp + Asset macro](https://github.com/webrouse/n-asset-macro/tree/master/examples/gulp) - [Webpack + Asset macro](https://github.com/webrouse/n-asset-macro/tree/master/examples/webpack) License ------- [](#license) N-asset-macro is under the MIT license. See the [LICENSE](LICENSE.md) file for details. ### Health Score 36 — LowBetter than 81% of packages Maintenance18 Infrequent updates — may be unmaintained Popularity35 Limited adoption so far Community13 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 96.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~90 days Recently: every ~119 days Total 9 Last Release 2670d ago Major Versions v0.1 → v1.02017-08-14 v1.2.2 → v2.0.02018-12-05 PHP version history (2 changes)v0.1PHP >=5.6 v2.0.0PHP >=7.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/87a255ed85b88822ef9f611bddf70b5a44f8c7f4c68b27f897b7e68116f7e0d5?d=identicon)[webrouse](/maintainers/webrouse) --- Top Contributors [![michaljurecko](https://avatars.githubusercontent.com/u/19371734?v=4)](https://github.com/michaljurecko "michaljurecko (26 commits)")[![mrceperka](https://avatars.githubusercontent.com/u/22822651?v=4)](https://github.com/mrceperka "mrceperka (1 commits)") --- Tags assetgruntgulplattemacronettewebpack ### Embed Badge ![Health badge](/badges/webrouse-n-asset-macro/health.svg) ``` [![Health](https://phpackages.com/badges/webrouse-n-asset-macro/health.svg)](https://phpackages.com/packages/webrouse-n-asset-macro) ``` ### Alternatives [nepada/form-renderer Latte template based form renderer for Nette forms with full support for Bootstrap 3, 4 & 5. 11251.0k](/packages/nepada-form-renderer)[nextras/forms-rendering Rendering helpers for Nette Framework Forms. 1698.4k2](/packages/nextras-forms-rendering) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)