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.


The RefreshCache snippet refreshes the cache by visiting all site pages that are published, undeleted, and cacheable.

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 cURL. The larger the site, the longer it takes.

On a 100-page site, at broadband speeds, it can take 4-10 minutes to run, depending on the connection speed 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.1.0-pl, RefreshCache has been refactored as a Custom Manager Page (CMP). It is more reliable, slightly prettier, and the RefreshCache Resource is no longer used. You can remove the RefreshCache Resource, but *don't* remove the RefreshCache snippet. The new version uses ExtJS/modExt rather than JQuery. It should run a little faster since the JavaScript is already loaded when you launch it in the Manager. The sleep times have also been shortened.

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 (AKA Web Transport Facility). 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 Components 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.


The only settable options are the two System Settings in the refreshcache namespace. The refreshcache_ajax_delay System Setting sets the number of milliseconds to sleep between Ajax requests for the file that contains the progress messages. The default is 200 milliseconds (.2 seconds). You can reduce that if RefreshCache is skipping messages. You can also increase it to take some pressure off the server. A good value is 900 if you want to avoid bot- blocking software like BotBlockX. At higher values, it will appear that some resources are being skipped, but in fact they are being refreshed (you can check the log to verify this). Only the progress message is being skipped.

Having the Ajax delay at .2 seconds does not mean that there will be 5 requests per second. The delay 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. Setting the delay to 0 will put a little more stress on the server, but should still work. Note that setting the delay will have no effect on the time it takes for the full process to finish. The refreshing occurs in the PHP code and is unaffected by the Ajax delay.

The refreshcache_curl_delay sets the number of seconds to sleep between page requests. The default is 0 seconds. You can take some pressure off your server by setting it higher, but that will slow down the program and the time-to-completion will go up. It shouldn't be necessary to change the refreshcache_curl_delay setting unless you are being blocked by bot-blocking software like BotBlockX, because each cURL request won't be issued until the previous page has fully loaded in the browser.


RefreshCache writes its Ajax log files to the assets/components/refreshcache/ directory. Make sure that directory is writable. After RefreshCache has finished, the refreshcache.log file should contain a list of all Resources that were refreshed with the total execution time at the end of the file.

Program Speed

How long it takes the process to finish depends on the browser you use and the speed of your internet connection. I notice that on my localhost install, RefreshCache runs about 20 times faster in Firefox than it does in Chrome. I have no idea why. At Bob's Guides, there are just under 200 Resources. RefreshCache takes about 27 minutes in Chrome and about 17 minutes in Firefox, so it's worth experimenting.

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 Settings

Setting Description Default
refreshcache_ajax_delay Delay between JS polling checks (in milliseconds) 900
refreshcache_curl_delay Delay between cURL requests (in seconds) 0


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