{"id":13756595,"url":"https://github.com/clubstudio/craft-asset-rev","last_synced_at":"2026-01-11T16:52:50.401Z","repository":{"id":29827709,"uuid":"33372285","full_name":"clubstudio/craft-asset-rev","owner":"clubstudio","description":"A Craft CMS plugin to help with cache busting","archived":false,"fork":false,"pushed_at":"2024-03-26T19:45:32.000Z","size":223,"stargazers_count":109,"open_issues_count":2,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-14T12:10:17.784Z","etag":null,"topics":["assets-manifest","cache-bust","craft-plugin","craftcms","craftcms-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clubstudio.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-03T16:38:05.000Z","updated_at":"2024-03-26T22:56:38.000Z","dependencies_parsed_at":"2024-06-18T13:42:13.211Z","dependency_job_id":"b4b6d7da-0dba-447f-852d-1b916501724a","html_url":"https://github.com/clubstudio/craft-asset-rev","commit_stats":{"total_commits":71,"total_committers":4,"mean_commits":17.75,"dds":0.04225352112676062,"last_synced_commit":"c4c6e6d11d79ede75a9a2751b248c042fe5ac763"},"previous_names":["clubstudio/craft-asset-rev","clubstudioltd/craft-asset-rev"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clubstudio%2Fcraft-asset-rev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clubstudio%2Fcraft-asset-rev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clubstudio%2Fcraft-asset-rev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clubstudio%2Fcraft-asset-rev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clubstudio","download_url":"https://codeload.github.com/clubstudio/craft-asset-rev/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224911608,"owners_count":17390840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assets-manifest","cache-bust","craft-plugin","craftcms","craftcms-plugin"],"created_at":"2024-08-03T11:00:48.547Z","updated_at":"2026-01-11T16:52:50.362Z","avatar_url":"https://github.com/clubstudio.png","language":"PHP","funding_links":[],"categories":["Build Tools"],"sub_categories":[],"readme":"\u003cimg src=\"./src/icon.svg\" width=\"64\"\u003e\n\n# CraftCMS Asset Rev / Cache Busting\n[![tests](https://github.com/clubstudioltd/craft-asset-rev/actions/workflows/tests.yml/badge.svg)](https://github.com/clubstudioltd/craft-asset-rev/actions/workflows/tests.yml)\n[![Latest Stable Version](https://poser.pugx.org/clubstudioltd/craft-asset-rev/v/stable)](https://packagist.org/packages/clubstudioltd/craft-asset-rev)\n[![Total Downloads](https://poser.pugx.org/clubstudioltd/craft-asset-rev/downloads)](https://packagist.org/packages/clubstudioltd/craft-asset-rev)\n[![Latest Unstable Version](https://poser.pugx.org/clubstudioltd/craft-asset-rev/v/unstable)](https://packagist.org/packages/clubstudioltd/craft-asset-rev)\n[![License](https://poser.pugx.org/clubstudioltd/craft-asset-rev/license)](https://packagist.org/packages/clubstudioltd/craft-asset-rev)\n\n**Looking for Craft 2 Support?** [Asset Rev for Craft 2](https://github.com/clubstudioltd/craft-asset-rev/tree/v5)\n\nA Twig extension for CraftCMS that helps you cache-bust your assets using configurable strategies.\n\n## Why?\nIn order to speed up the load time of your pages, you can set a far-future expires header on your images, stylesheets and scripts. However, when you update those assets you'll need to update their file names to force the browser to download the updated version.\n\nUsing a manifest file is the recommended approach - you can read up on why using query strings isn't ideal [here](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/).\n\n## Strategies\nThis plugin allows you to configure multiple cache-busting strategies for your asset filenames.  The plugin comes with three strategies out of the box:\n\n### Manifest File\n`css/main.css` will be replaced with the corresponding hashed filename as defined within your assets manifest `.json` file.\n\nIf the contents of your manifest file are...\n\n```json\n{\n    \"css/main.css\": \"css/main.a9961d38.css\",\n    \"js/main.js\": \"js/main.786087f5.js\"\n}\n```\n\nthen `rev('css/main.css')` will expand to `css/main.a9961d38.css`.\n\n**Please note:** This plugin __does not__ create manifest files; instead they should be generated during your build process using [Gulp Rev](https://github.com/sindresorhus/gulp-rev), [Laravel Mix](https://github.com/JeffreyWay/laravel-mix) or another comparable tool.\n\n### Query String\nAppend a query string to your file, based on the time it was last modified. For example: `rev('css/main.css')` will expand to something like `css/main.css?1473534554`.\n\n### Passthrough\nReturns the original filename, without modification. This is useful if all other cache-busting strategies fail.\n\n## Strategy Pipeline\nPipelines allow you to attempt multiple cache-busting strategies in sequence. If one strategy fails, the plugin can proceed to try and cache-bust the asset filename using the next strategy in the pipeline.\n\nThe default pipeline is `manifest|querystring|passthrough` and will:\n\n1. Attempt to use the `ManifestFileStrategy`. If it can’t, because the manifest file doesn’t exist, it will throw a `ContinueException` that defers cache-busting to the next strategy in the pipeline…\n2. Attempt to use the `QueryStringStrategy`. If it can’t, because it can’t find the asset file, it will throw another `ContinueException` that defers cache-busting to the final default strategy…\n3. Returns the original filename using the closure-based pass-through strategy.\n\n**Need to provide your own cache-busting logic?** Simply create your own implementation of the Strategy class or define a Closure in the configuration file.\n\n## Installation\nInstall via the Plugin Store within your Craft 3 installation or using Composer: `composer require clubstudioltd/craft-asset-rev`\n\n## Configuration\nThe plugin comes with a `config.php` file that defines some sensible defaults.\n\nIf you want to set your own values you should create a `assetrev.php` file in your Craft config directory. The contents of this file will get merged with the plugin defaults, so you only need to specify values for the settings you want to override.\n\n### Strategies\n`strategies` is where you define the strategies you'd like to try to rev your asset filename. You can provide the name of a class that implements `StrategyContact` or a custom closure. The defaults should cater to most requirements.\n\n### Pipeline\n`pipeline` allows you to set the order of the configured strategies you'd like to try when revving your asset file names. The default of: `manifest|querystring|passthrough` should be adequate for most use-cases.\n\n### Manifest Path\n`manifestPath` is where Craft should look for your manifest file. Non-absolute paths will be relative to the base path of your Craft installation (whatever `CRAFT_BASE_PATH` is set to).\n\n### Assets Base Path\n`assetsBasePath` is the the base path to your assets. Again, this is relative to your craft base directory, unless you supply an absolute directory path.\n\n### Asset Url Prefix\n`assetUrlPrefix` will be prepended to the output of `rev()`.\n\n**Note:** You can use Yii aliases in your configuration values.\n\n## An Example Config File\n```php\n\u003c?php\nreturn array(\n    '*' =\u003e array(\n        'strategies' =\u003e [\n            'manifest' =\u003e \\club\\assetrev\\utilities\\strategies\\ManifestFileStrategy::class,\n            'querystring' =\u003e \\club\\assetrev\\utilities\\strategies\\QueryStringStrategy::class,\n            'passthrough' =\u003e function ($filename, $config) {\n                return $filename;\n            },\n        ],\n        'pipeline' =\u003e 'manifest|querystring|passthrough',\n        'manifestPath' =\u003e 'resources/assets/assets.json',\n        'assetsBasePath' =\u003e '../public/build/',\n        'assetUrlPrefix' =\u003e '@web/assets',\n    ),\n);\n```\n\n## Usage\nOnce activated and configured you can use the `rev()` function in your templates.\n\n```html\n\u003clink rel=\"stylesheet\" href=\"{{ rev('css/main.css') }}\"\u003e\n```\n\n## Custom Strategies\nNeed to provide your own cache-busting logic? Create your own Strategy class or simply use a Closure.\n\n### Example Strategy Class\n```php\n\u003c?php\n\nnamespace your\\namespace;\n\nuse club\\assetrev\\utilities\\Strategy;\nuse club\\assetrev\\exceptions\\ContinueException;\n\nclass QueryStringStrategy extends Strategy\n{\n    public function rev($filename)\n    {\n        // add your logic to manipulate $filename here...\n        return $filename;\n    }\n}\n```\n\n### Example Closure\nYour method will have access to the asset filename and the plugin configuration array.\n\n```php\nfunction ($filename, $config) {\n    // add your logic to manipulate $filename here...\n    return $filename;\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclubstudio%2Fcraft-asset-rev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclubstudio%2Fcraft-asset-rev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclubstudio%2Fcraft-asset-rev/lists"}