RefreshCache Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


RefreshCache refreshes the cache by visiting all site pages that are published, undeleted, and cacheable, as long as they are not hidden in some way.

The point is for this program to spend time waiting for the pages so the site visitors don't have to. They'll see cached pages, which will be delivered much faster.

RefreshCache is an inelegant, brute-force extra. It refreshes the cache by requesting every page with Guzzle (which uses cURL or streams). The larger the site, the longer it takes. In many cases, CacheMaster, which clears only the cache for the current resource being saved is a better choice, especially on very large sites.

On a 100-page site, at broadband speeds, RefreshCache can take 4-10 minutes to run, depending on the connection speed, the browser, and how complex the pages are. Larger sites can take much longer, especially if there are lots of images to load, lengthy getResources calls, or complex conditional output modifiers. The longer it takes RefreshCache to run, the more valuable it is to your site's visitors.

As of Version 1.2.0-pl, RefreshCache has been completely refactored to eliminate PHP timeouts. It has been tested by simulating a site with over 100,000 pages. It is much simpler, slightly prettier, and the RefreshCache Resource and snippet are no longer used. You can remove the RefreshCache Resource if it's still there. The RefreshCache snippet should be removed automatically during the upgrade. The new version reverts to using JQuery and requires Guzzle 6. It should run a little faster since the sleep times have been shortened.

Important: Guzzle 6 requires PHP >= 5.4.

Installing RefreshCache

Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository. Put RefreshCache in the search box and press Enter. Click on the "Download" button, and when the download is finished, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to RefreshCache in the grid. The RefreshCache package should now be installed.

After installing RefreshCache, you'll need to reload the Manager page before it will show up under the Extras menu. In fact, if you don't already have any components installed, the Components menu itself won't appear until after you install RefreshCache and then reload the Manager page.


To run RefreshCache, just select the RefreshCache menu item under Components in the Manager's Top Menu. Remember that you'll need to reload the Manager page after installing RefreshCache before the menu item will show up. Once RefreshCache has launched, click on the "Refresh the Cache" button at the top of the page. Important: Do not close the browser window or navigate to another page until RefreshCache has finished.

For security, only members of the Administrator group can run RefreshCache and it can only be run from inside the MODX Manager.

If you are using the Articles blog, RefreshCache will refresh Articles along with other Resources. It will refresh anything obtainable with getCollection('modResource'). If snippet results or chunks are processed and cached on any cacheable pages, it will refresh those as well. It will not refresh the cache for resources that are unpublished or restricted in some way.


The only settable options are the two System Settings in the refreshcache namespace. The refreshcache_request_delay System Setting sets the number of milliseconds to sleep between Ajax requests for the file that contains the progress messages. The default is 0 milliseconds, though there is some inherent delay in the process. You increase it to take some pressure off the server. A good value is 900 if you want to avoid bot- blocking software like BotBlockX.

Having the Request delay at 0 seconds does not mean that there will be many requests per second. RefreshCache now uses a tail-call-optimized, recursive Ajax function, so every request is started after the previous one has finished. The Request delay (if any) occurs after the Ajax request is completed, so the actual interval will be however long it takes for the Ajax request to complete, plus the delay. The initial delay is set to 0 and will vary depending on each page's load time.

Some servers may complain about the repeated calls and could throttle them. You might also experience trouble with your browser popping up a message about excessive looping. Usually you can click on "wait," "OK," or "Continue" to resume RefreshCache. The results may depend on how well your browser optimizes recursions in JavaScript and on its stack limit.

The refreshcache_log_all_errors setting determines if all page access errors are logged to the MODX error log. Most of these will be 401, 403, or 404 errors caused by inaccessible pages that require login or special conditions for access.


RefreshCache now shows the pagetitles of resources it is refreshing the cache for, and no longer writes a log (though the refreshcache_log_all_errors System Setting will let you log all refresh failures). When finished, it will report how many resources were updated.

Program Speed

How long it takes the process to finish depends on the browser you use, the speed of your internet connection, and the page-load time of each resource. I notice that on my localhost install, RefreshCache runs faster in some browsers than others. This depends on how well the browser optimizes JavaScript code. I ran a simulation with over 100,000 resources on Chrome and it took around 24 hours.

Important Warning!

RefreshCache visits every published, cacheable page on your site. If you have snippet tags on such a page, the snippets will run. If you have a page with a snippet that automatically sends an email (e.g., QuickEmail), you'll get an email. If you have a utility snippet that modifies the database, the database will be modified. I generally leave such pages unpublished, but you might not, so think about what will happen if every cacheable, published page is visited.

RefreshCache System Settings

Setting Description Default
refreshcache_request_delay Delay between JS calls (in milliseconds — 1000 = 1 second) 0
refreshcache_log_all_errors Log all access errors to the MODX error log No


My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting

  —  Bob Ray