Cache Busting

How Magento Handles Versions

Magento uses version strings in file URLs:

<link rel="stylesheet" href="pub/static/frontend/Vendor/Theme/en_US/css/styles.css?v=1234567890">
<script src="pub/static/frontend/Vendor/Theme/en_US/js/main.js?v=1234567890"></script>

Version Generation

# Deploy with version
bin/magento setup:static-content:deploy -f

# Check version in URLs
bin/magento dev:static-content:version

Configuration

<!-- app/etc/config.xml -->
<config>
    <default>
        <dev>
            <static>
                <sign>1</sign>  <!-- Enable version signing -->
            </static>
        </dev>
    </default>
</config>

Version in URLs

// Get versioned URL
$url = $this->getViewFileUrl('css/styles.css');
// Returns: pub/static/frontend/Vendor/Theme/en_US/css/styles.css?v=...

// Without version
$url = $this->getViewFileUrl('css/styles.css', ['_version' => null]);

Content-Based Hashing

# Magento uses file modification time for versioning
# Files are versioned when deployed

# Check file hash
md5sum pub/static/frontend/Vendor/Theme/en_US/css/styles.css

Custom Versioning

// In custom module
class VersionedUrl
{
    public function getVersionedUrl(string $file): string
    {
        $filePath = BP . '/pub/static/' . $file;
        $hash = md5_file($filePath);
        
        return $this->baseUrl . $file . '?v=' . $hash;
    }
}

RequireJS Versioning

// requirejs-config.js
var config = {
    urlArgs: 'v=' + new Date().getTime()
};

// Or use content hash
var config = {
    urlArgs: 'v=' + contentHash
};

Browser Caching

# .htaccess
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 1 year"
    ExpiresByType application/javascript "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType image/jpeg "access plus 1 year"
</IfModule>

CDN Setup

# nginx configuration
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    add_header Vary "Accept-Encoding";
}

Magento CDN Config

# Set base URL to CDN
bin/magento config:set web/secure/base_url https://cdn.example.com/
bin/magento config:set web/unsecure/base_url https://cdn.example.com/

# Or use different domains for static
bin/magento config:set web/secure/base_static_url https://static.example.com/
bin/magento config:set web/unsecure/base_static_url https://static.example.com/

CDN Headers

# Cache static assets for 1 year
<IfModule mod_headers.c>
    <FilesMatch "\.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$">
        Header set Cache-Control "max-age=31536000, public"
        Header set Vary "Accept-Encoding"
    </FilesMatch>
</IfModule>

CDN Purging

// Purge CDN cache
public function purgeCdnCache(): void
{
    $files = [
        'css/styles.css',
        'js/main.js'
    ];
    
    foreach ($files as $file) {
        $this->cdnClient->purge($file);
    }
}

Strategy 1: Query String

<link rel="stylesheet" href="styles.css?v=1234567890">

Pros: Simple, widely supported
Cons: Some proxies ignore query strings

Strategy 2: Filename Hash

<link rel="stylesheet" href="styles.abc123.css">

Pros: Works with all CDNs, cache invalidation on change
Cons: More complex to implement

Strategy 3: Content Hash

<link rel="stylesheet" href="styles.contenthash.css">

Pros: Automatic invalidation when content changes
Cons: Build process required

Magento Implementation

// Magento uses query string versioning
public function getFileUrl(string $file): string
{
    $url = $this->assetRepository->getUrl($file);
    return $url . '?v=' . $this->getVersion();
}

private function getVersion(): string
{
    return (string) filemtime(
        BP . '/pub/static/' . $this->file
    );
}

Best Practices

• Use version strings for all static assets
• Set long cache headers (1 year)
• Use immutable assets when possible
• Purge CDN cache on deployment
• Test cache busting in staging