Magento 2 Full Page Cache DocumentationFull Page Cache

« Back to Magento 2 Full Page Cache

  • Installation

    You can install the module for Magento 2 using Composer or you can manually install it using FTP.

    • Run the following commands in your Magento 2 root directory to install the module using Composer.

      # Add the FishPig Composer repo
      composer config repositories.fishpig composer https://repo.fishpig.co.uk/
          
      # Install the module using Composer
      composer require fishpig/magento2-bolt:*
      
      # Enable the module in Magento 2
      php bin/magento module:enable FishPig_Bolt
      
      # Run the Magento upgrade system
      php bin/magento setup:upgrade
    • You can download the latest version of the module from the Downloads page.

      Extract the ZIP file and upload the files to your Magento site at the directory below:

      app/code/FishPig/Bolt

      When creating the folders, ensure you use the correct capitalisation.

      To complete the installation, run the following commands in a terminal.

      # Enable the module in Magento 2
      php bin/magento module:enable FishPig_Bolt
      
      # Run the Magento upgrade system
      php bin/magento setup:upgrade

    With the extension installed, we need to make a small modification to Magento's index.php. Open index.php (this will be in your Magento root or the pub directory) using FTP and find the following line:

    $bootstrap = \Magento\Framework\App\Bootstrap::create(BP, $params);

    Right above this line, you need to add a single line. Below is what it should look like after you make the adjustment.

    \FishPig\Bolt\App::create(BP, isset($params) ? $params : $_SERVER);
    
    $bootstrap = \Magento\Framework\App\Bootstrap::create(BP, $params);

    This will enable Bolt for your Magento frontend. You can also enable debugging if you are having any issues. To do this, make the following adjustments:

    $params[\FishPig\Bolt\App::DEBUG_FLAG] = true;
    
    \FishPig\Bolt\App::create(BP, $params);
    
    $bootstrap = \Magento\Framework\App\Bootstrap::create(BP, $params);

    ↑ Back to Top

  • Configuration

    The Full Page Cache module comes ready configured but if you want to make any changes, you can do so in the Magento Admin by selecting: Stores > Configuration > FishPig > Full Page Cache.

    Multistore

    Bolt fully supports Magento multistore and you do not have to make any configuration changes for Bolt to run in a multi-store environment.

    Cache Backends

    The Full Page Cache module supports the standard files cache and session types, as well as Redis. This will be taken automatically from your app/etc/local.xml file.

    Troubleshooting

    To check that Bolt is running and has cached the current page, use your browsers developer tools to check the headers of the HTTP Response. When Bolt has cached a page, the X-Cached-By: Bolt header will be set. If this header is not set then the current page has not been retrieved from the cache.

    ↑ Back to Top

  • Hole Punching

    The more that can be cached on a page, the faster it will be. Unfortunately it's not always possible to cache the whole page as certain sections are completely dynamic and unique to each user. To get around this, Bolt uses a hole punching system.

    What is Hole Punching?

    Hole punching is a system that allows you to mark certain sections of a page to be loaded each time and never cached while still caching the rest of the page. Bolt will load a page from the cache and then fill in the holes with dynamic content. In Magento, the most common block to be hole punched is the header, as this usually contains dynamic content such as a shopping cart summary and different links depending on whether the customer is logged in or not. As this is such a commonly hole punched block, Bolt will hole punch this block automatically so you don't need to add this to the hole punch list.

    Default Hole Punch Configuration

    By default, Bolt will automatically hole puncht the 'header' block. For 90% of Magento installtions, this is the only block that will need hole punching, which means that you don't need to make any changes to the hole punch configuration. If you do need to add a new block to the hole punch, keep reading.

    Add a Block to the Hole Punch

    To add a new block to the hole punch, login to the Magento Admin and select Stores > Configuration > Bolt and then find the Hole Punch section. After making any changes to the hole punch you will need to flush the Bolt cache for these changes to take affect.

    Click the 'Add New' button to create a new row for the Hole Punch. You should see 2 fields: Block Name and Punch a Hole.

    Block Name

    The Block Name fields expect the name of the block that you want to hole punch. This name is the name of the block in your XML layout. If you are unsure of what this is, there is an easy way to find out. Find the template that the block uses (if you aren't sure which template, enable Template Path Hints in System > Developer > Template Path Hints. You will need to change to the store scope to see this configuration option) and open that template using FTP. Inside th template, add the following code to the top:

    <?php echo 'Block Name: ' . $this->getNameInLayout(); exit; ?>

    This code will write out the name of the block in the XML layout. This is the exact value that you need to use for the 'Block Name' field in the configuration.

    Punch a Hole

    The punch a hole field allows you to configure when a block should be hole punched and when it should be loaded from the cache. There are 4 options for this field.

    Always

    This option will trigger Bolt to always hole punch the block and load it dynamically. Bolt will never load the block from the cache.

    When items are in the cart

    This option will trigger Bolt to load the block from the cache until the customer adds a product to their cart, at which point the block will be loaded dynamically. If the customer removes all products from their cart, Bolt will load the block from the cache.

    When the customer is logged in

    This option will trigger Bolt to load the block from the cache until the customer logs in to their account, at which point the block will be loaded dynamically. If the customer logs out, the block will be loaded from the cache.

    When items are in the cart or the customer is logged in

    This option will trigger Bolt to load the block from the cache until either the customer logs in to their account or the customer adds a product to their shopping cart. If the customer logs out of their account and removes all products from their shopping cart, the block will be loaded from the cache again.

    Hole Punch Cache

    To make the hole punch even faster, Bolt uses a caching system on the hole punch. If you have any problems with the Hole Punch and find that incorrect content is displaying, try disabling this feature (Stores > Configuration > FishPig > Full Page Cache > Hole Punch > Cache).

    ↑ Back to Top

  • Cli Commands

    The module comes with a handy command line utility that allows you to flush the whole cache or just specific URLs easily.

    Empty the Cache

    The below command will empty the whole cache. This includes all pages from all stores/websites.

    bin/magento fishpig:bolt:flush

    Remove Specific URLs from the Cache

    If you don't want to remove everything from the cache but just want to remove a single URL, you can do so by passing options to the flush command.

    --url

    You can specify as many URL arguments as you like. The URL should be a relative URL.

    bin/magento fishpig:bolt:flush --url /mens/jackets.html

    You can specify multiple URLs in a single command.

    bin/magento fishpig:bolt:flush --url /mens/jackets.html --url /womens/jackets.html

    By default, all child pages of a given URL are flushed from the cache. This includes all different variations of the page (ie. query string parameters).

    --store

    By default, the URL will be removed from the cache for every store. You can limit the stores using the store option.

    bin/magento fishpig:bolt:flush --url /mens/jackets.html --store 1 --store 2

    You can also specify a store code rather than a store ID.

    bin/magento fishpig:bolt:flush --url /mens/jackets.html --store default

    --protocol

    By default, the URL will be flushed for both https and http. If you only use one protocol on your site (ie. just https), it will be quicker to just specify https and skip http.

    bin/magento fishpig:bolt:flush --url /mens/jackets.html --protocol https

    Flush a Whole Website Section

    Let's say you have a Magento WordPress integrated blog on your site that is available from /blog and you want to flush the whole blog from the cache. The following command will do that:

    bin/magento fishpig:bolt:flush --url /blog

    This will flush the /blog URL but also flush all children URLs of /blog and will empty all of the blog from the cache for every store. You can limit this to a specific store with the stores option (see above).

    ↑ Back to Top