Download the PHP package bagisto/bagisto-varnish without Composer

Varnish Integration for Bagisto

This package puts Varnish Cache in front of a Bagisto storefront, so a cached page is served without touching PHP at all, while personalised parts of the page still come from the application through ESI (Edge Side Includes) or AJAX dynamic views.

📌 Features

• ⚡ Full-page caching via Varnish
• 🔄 Automatic cache purging when a product, category, page, section or configuration changes
• 🔍 ESI support for dynamic blocks
• 🖱 AJAX-based dynamic view loading for improved Core Web Vitals
• 🛠 Artisan command for cache management
• 🖥 Admin tools for purging cache and exporting a ready-made VCL
• 🎨 Theme-ready Blade components
• 🛡 Middleware that tags responses and sets cache headers

🔄 How it fits together

Varnish sits between your public web server and Bagisto. Three processes, three ports:

The single most common mistake is confusing the two host settings. They describe different hops, and getting them the wrong way round fails silently — pages cache but never update:

Ports above are examples — use whatever your server actually listens on. Confirm with:

✅ Requirements

• Bagisto 2.5.x
• PHP 8.4+ (matching Bagisto 2.5's own ^8.4)
• Varnish 6.0 or newer (tested on 6.x and 7.x)

On an older Bagisto, install the matching package version from the table below instead — the releases are not interchangeable, because each one tracks the storefront views and the configuration tree of its own Bagisto line.

Version compatibility

The PHP range is Bagisto's own for that line; only 2.2.0 declares php in its composer.json. Varnish 6.0+ applies to every row.

Two upgrades are not drop-in, so check them before moving between lines:

Development happens on a single master branch, which tracks the newest Bagisto line. There is no long-lived 2.4 branch: the 2.4 line is held by the v2.1.0 tag.

📦 Installation

1. Install via Composer

2. Register the service provider

Bagisto 2.5 keeps providers in bootstrap/providers.php, which returns a flat array — not the 'providers' => [...] block used by older Laravel versions:

Order matters, and auto-discovery is deliberately disabled. The provider re-registers the cache.response middleware alias so storefront routes are tagged for Varnish instead of being stored by Bagisto's built-in page cache. Registered before the Shop package, the Shop package would simply overwrite it again and nothing would be tagged.

3. Publish the config

⚙️ Configuration

Do this before exporting the VCL — the VCL file is generated from these values.

Go to Admin → Configuration → Cache Management → Varnish → Configuration.

1. Set Cache Application to Varnish.

   The remaining fields stay hidden until you do — they depend on this one. If you cannot see the settings below, this is why.

2. Fill in the rest:

3. Save.

Keeping the settings

These live in core_config, so anything that rebuilds the database (bagisto:install, which runs db:wipe + migrate:fresh) removes them. On a demo or CI environment that reinstalls regularly, seed the values instead of entering them by hand.

🖥 Install the VCL

1. Admin → Configuration → Cache Management → Varnish → Configuration → Export VCL. The downloaded file already contains the backend host, port, access list and grace period you configured above.

2. Put it in place and reload:

   The -C step compiles without applying — always run it first, since a bad VCL will stop Varnish from starting.

3. Purge everything once, so nothing cached under an older configuration is left behind.

A ready-made copy also ships at vcls/6.0.vcl for reference, but prefer the exported file: that one carries your own settings.

🔬 Verify it is working

X-Bagisto-Cache-Debug reports HIT, MISS or UNCACHEABLE. If you never see HIT, Varnish is not in the request path. If you see HIT but it never returns to MISS after an edit, your Varnish Host URL is wrong.

🛡 Automatic cache purging

Purging happens on its own when:

• A product is created, updated or deleted — its own page, its category pages and the home page.
• A category is created, updated or deleted — its page in every locale, and the home page.
• A CMS page, review, order, refund or URL rewrite changes.
• A section is published, created or deleted under Appearance. Footer and services sections are drawn by the sitewide layout, so they drop the whole cache; any other section drops the home page. Editing, reordering and toggling a section are held as drafts and purge nothing until you press Publish.
• A channel is updated, which includes activating a different theme.
• Any configuration is saved.

A purge clears the page in every channel, locale and currency it was cached under, so it does not matter which locale the admin happened to be in when saving.

To purge from your own code:

Or from the command line:

Upgrading from an older version: a cached page carries the tags it will later be purged by, so pages already sitting in Varnish still hold the old tag format. Run Purge Everything once after deploying.

🛠 Manual cache management

Admin → Configuration → Cache Management → Varnish → Purge Cache

• Purge by URLs — one or more full URLs or paths, separated by commas or newlines.
• Purge Everything — drops every cached object, including static assets and ESI fragments that Bagisto never tagged.

🎨 Theme integration

Personalised fragments must be pulled out of the cached page. Declare each one in config/varnish.php:

• Key → the identifier used in the ESI or AJAX call
• Path → the Blade view to render

Then include it one of two ways:

ESI include

Assembled by Varnish itself, so it is present in the first paint. A slow backend will hold up the whole page.

AJAX dynamic view — recommended

Fetched after the page renders. Better LCP/FCP, and the right choice for dropdowns, modals and menus that are not needed immediately.

🗂 Cache-Control headers

Routes that should be cached carry:

The lifetime goes to s-maxage, which only shared caches such as Varnish honour, while browsers are asked to revalidate. This matters: a purge reaches Varnish alone, so giving the same lifetime to max-age would leave every visitor who had already loaded the page holding a private copy for a week that nothing could invalidate.

Routes that must not be cached should send:

Attach the middleware to any route you want cached and tagged:

The lifetime is a middleware argument in minutes — cache.response:1440 for a day. It defaults to 7 days.

🧯 Troubleshooting

🚀 Best practices

• Use ESI for small, critical personalised blocks (login status, cart count).
• Use AJAX dynamic views for everything else, to protect Core Web Vitals.
• Never cache /customer or /checkout — the shipped VCL already bypasses both.
• Compile a VCL with varnishd -C before reloading it.
• Test on staging first, and watch LCP, FCP and TTFB after enabling Varnish.