Componette

Componette

nepada

nepada / bust-cache v3.1.0

Cache busting Latte tag.

download-cloud-line composer require nepada/bust-cache

Bust Cache Latte Tag

Build Status Coverage Status Downloads this Month Latest stable

Installation

Via Composer:

$ composer require nepada/bust-cache

Register the extension in config.neon:

extensions:
    bustCache: Nepada\Bridges\BustCacheDI\BustCacheExtension(%wwwDir%, %debugMode%)

Overview of available configuration options with their default values:

bustCache:
  strategy: contentHash # modificationTime in debugMode
  autoRefresh: %debugMode%
  manifest: true
  strictMode: false

If you're using stand-alone Latte, install the Latte extension manually:

$fileSystem = Nepada\BustCache\LocalFileSystem::forDirectory($wwwDir);
$manifestFinder = new Nepada\BustCache\Manifest\AutodetectManifestFinder($fileSystem);
$revisionFinder = new Nepada\BustCache\Manifest\DefaultRevisionFinder($fileSystem, $manifestFinder);
$cache = new Nepada\BustCache\Caching\NullCache(); // or other implementation of Cache
$strategy = new Nepada\BustCache\CacheBustingStrategies\ContentHash(); // or other strategy
$pathProcessor = new Nepada\BustCache\BustCachePathProcessor($fileSystem, $cache, $revisionFinder, $strategy);
$latte->addExtension(new Nepada\Bridges\BustCacheLatte\BustCacheLatteExtension($pathProcessor, $strictMode, $autoRefresh));

Usage

Basic example:

<link rel="stylesheet" href="{bustCache /css/style.css}">

The resulting path depends on the (auto-)chosen cache busting strategy:

<!-- using path from revision manifest -->
<link rel="stylesheet" href="/css/style-30cc681d44.css">

<!-- using query cache busting with modificationTime strategy: timestamp of the last file modification -->
<link rel="stylesheet" href="/css/style.css?1449177985">

<!-- using query cache busting with contentHash strategy: first 10 letters of md5 hash of the file content -->
<link rel="stylesheet" href="/css/style.css?a1d0c6e83a">

Usage in application with non-trivial base path:

<link rel="stylesheet" href="{$basePath}{bustCache /css/style.css}">

Generating full absolute URL:

<link rel="stylesheet" href="{$baseUrl}{bustCache /css/style.css}">

Revision manifest support

Revision manifest is a JSON file that contains mapping between original asset path and its revision path.

Example:

{
    "css/style.css": "css/style-30cc681d44.css",
    "js/app.js": "js/app-68130ccd44.js"
}

Configuration

With default configuration the path of manifest file is auto-detected by traversing up from asset directory and looking for manifest.json or rev-manifest.json. If a manifest file is found, the contained revision mapping is used instead of cache busting using query parameter.

You can completely disable the revision manifest support by setting manifest: false in your config.

You can also bypass the auto-detection and specify the manifest file path statically, e.g. manifest: "assets/my-manifest.json"

Caching

The caching is implemented on two levels - runtime and compile-time.

Runtime caching

The cache stores the computed cache busted path for each input path.

DI extension automatically enables this cache, if you have nette/caching configured. In production mode with default settings, asset files are not checked for modification to avoid unnecessary I/O, i.e. the cache is not automatically refreshed.

Compile time caching

When the file path is specified as literal string, the cache busted path is computed in compile time of Latte template and the cache busted path is directly dumped into the compiled code of template.

With the default settings, this is enabled only in production mode.

Cache busting of files that are modified in app runtime

If you want to use cache busting on files that are expected to be modified in app runtime, you can use dynamic keyword to opt-out of compile time caching and force auto refresh of cache even in production mode:

<link rel="stylesheet" href="{bustCache dynamic /css/theme.css}">

Handling of missing manifest or asset files

With default configuration, when a missing file (manifest or asset) is encountered a warning triggered and asset dummy path is generated. You can switch to strictMode: true to fail hard by throwing exception instead.

"Missing file" is one of the following cases:

  • the static manifest file specified in configuration does not exist
  • a manifest file points to a revision path that does not exist
  • using cache busting by query parameter with asset path that does not exist
  • v3.1.0 3.1.0

    • Drop support for PHP <8.1
    • Use public readonly properties and property promotion to simplify DTOs
    • Drop useless annotations
    • PHP 8.3 compatibility
  • v3.0.2 3.0.2

    • PHP 8.2 compatibility
  • v3.0.1 3.0.1

    • Fixed Windows compatibility (thanks @lachmart)
  • v3.0.0 3.0.0

    Major rewrite for Latte 3 and PHP 8.

    New

    • Improved compile time and runtime caching:
      • This enables previously discouraged usage of bustCache tag in combination with path specified by a variable.
      • Possibility to explicitly opt-out of compile-time cache and force auto-refresh of runtime cache by dynamic keyword, e.g. {bustCache dynamic /file.css} (useful for files that are expected to be modified in app runtime).
    • Support for revision manifest file. Revisions from manifest file, if available, are preferred over query parameter cache busting.
    • Configurable handling of missing files. In strict mode (disabled by default) an exception is thrown, otherwise only a warning is triggered and dummy asset path is printed.
  • v2.4.1 2.4.1

    • Fixed filter name case.
    • Restrict maximum supported PHP version in composer.json.
  • v2.4.0 2.4.0

    • PHP 8.1 compatibility.
  • v2.3.1 2.3.1

    • Compatible with PHP 8.0.
  • v2.3.0 2.3.0

    • Requires PHP >=7.4.
    • Uses native property typehints.
  • v2.2.0 2.2.0

    • Requires PHP >=7.2.
    • PHP 7.4 compatibility.
  • v2.1.0 2.1.0

    • Requires Latte 2.5 and optionally Nette 3.0 (Nette 2.4 support was dropped).
  • v2.0.2 2.0.2

    • Fixed compatibility with Latte 2.5
  • v2.0.1 2.0.1

    • Fixed compatibility with Latte 2.5
    • Initial support for Nette DI 3.0
    • CI improvements
  • v2.0.0 2.0.0

    • Refactored exception hierarchy - unlikely, but possible BC break.
    • Code style and type safety improvements.
  • v1.1.1 1.1.1

    • Code style improvements.
  • v1.1.0 1.1.0

    • Requires Latte 2.4 and PHP 7.1.
    • Uses declare(strict_types = 1).
    • Uses scalar and return type hints.
    • Compatible with PHP 7.2.
  • v1.0.1 1.0.1

    • Code style improvements.
    • Tests against Nette 2.4.
  • v1.0.0 1.0.0

    • Initial release.
bar-chart-fill

Statistics

download-cloud-fill
10413
star-fill
5
bug-fill
0
flashlight-fill
28d
price-tag-2-line

Badges

guide-fill

Dependencies

php (>=7.1.0)
latte/latte (^2.4.4@dev)
Componette Componette felix@nette.org