RefreshCache Snippet Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $10.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-premium extras with a clear conscience.

As of version 1.3.0-pl, RefreshCache refreshes the cache by using MODX internal methods to generate the cached Resources. Along the way, it will cache elements like snippets and chunks used by the Resources when possible. It is fully compatible with MODX 3 and PHP 8.

It's now much faster than previous methods, which used cURL to visit each page. It will no longer affect hit counters, and is less likely to cause side effects by executing snippets or plugins attached to the Resources. It will also now refresh the cache for Resources hidden by permission rules, and it will refresh Articles (though not the Articles container).

It skips Resources that are deleted, unpublished, not marked as cacheable, and (optionally) snippets hidden from menus.

By default, MODX deletes the Resource and Element caches, so page loads can be slow until each page is visited by a site visitor. With RefreshCache, you can Refresh the cache in as little as 3 to 5 seconds for a 100-page site.

(Jump to Properties Table.)

Installing RefreshCache

Go to Extras -> Installer on the MODX Main Menu to launch Package Manager. 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.


There are now three different ways to run RefreshCache

As a CMP

Click on the Extras main-menu item and select "Refresh Cache." Click on the "Refresh the Cache" button. RefreshCache will show a progress bar and the names of the Resources being refreshed. When it's finished, you'll see the number of resource cache files it has refreshed and the elapsed time.

This is the slowest method, because of the JavaScript involved. This method will typically refresh about 3-7 Resources per second. Pages that already have cache files will take less time. Pages with a lot of built-in processing may take longer.

See the troubleshooting section below if the process does not finish or shows an error in red in the progress window.

As a Snippet

To run the snippet, simply view the "RefreshCache" resource. You'll see a blank page for a while. Be patient, nothing will be displayed until RefreshCache has refreshed all cacheable pages. When it's finished, then the list of refreshed Resources will appear. This is much faster than the previous method. It should refresh 20 to 100 resources per second, depending on how complex the pages are (how many snippets are called in the Template and Resource, and how many tags have to be parsed) and whether the pages are already cached.

Remember that you'll need to reload the Manager page after installing RefreshCache before the RefreshCache Resource will show up. Important: Do not close the browser window or navigate to another page until RefreshCache has finished.

Any Manager user can run RefreshCache with this or the previous method, but you can hide the page with permission rules. You can also hide the CMP on the Extras menu by providing it with a custom permission that only selected users have.

As a Cron Job

Thanks to Michael Snow, RefreshCache can be run as a cron job. Just point your cron job at path/to/modx/core/components/refreshcache/RefreshCacheCRON.php. Be sure to get the spelling of the file name right, especially if you are on a server where file names are case-sensitive.

This is the fastest method, and it can refresh as many as 130 Resources per second. I would not recommend setting it to run too often — once per hour (or, better) once per day). Because of this, I prefer to run RefreshCache manually when I've done work on the site.

If you are on a Mac, there is a version of a cron job file for you in core/components/refreshcache/_MACOSX directory. That version has not been tested lately, and it has not been updated for version 1.3.0-pl, but it may still work.

There are variables in the RefreshCacheCRON.php file that set various options. Some of them are set by the RefreshCache System Settings. Others have to be set manually in the file. You have the option to have the run reported to the MODX Error Log, or in an email, or both. If you edit the file and set $debug = false it will run even faster.

The cron job (and the snippet) will not run if there are already lots of files in the Resource cache. The number is set to 350. If there are more than 350 cache files already, RefreshCache will not run. You can change that value in the RefreshCacheCRON file.

If you have cPanel, it should have Cron Jobs in the Advanced section. There's a wizard that will help you set the time and frequency of the cron job. Be sure to get the case of the file (RefreshCacheCRON.php) correct if you are on a server like Apache, where file names are case-sensitive.

Speed Considerations

The CMP version uses a tail-call-optimized, recursive Ajax function, so every request is started after the previous one has finished. The Request delay you set in the System Settings (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. I have not encountered these problems, but the largest site I've run it on had 198 cacheable resources.

In all versions (CMP, snippet, and cron job), there is one server request to get the list of resources, and another one for each resource that is refreshed.

Having a delay of 0 does not mean the actual delay is that short. There is an inherent delay because of the time to make each request and create the cache file, and a longer one for the CMP version because of the JavaScript.

If you use a bot blocker like BotBlockX to prevent bots from scraping the site, it may interfere with RefreshCache unless you increase the delay. A one-second delay (or even less) should be enough to prevent that. If you use a delay less than one second, put a leading 0 ahead of the decimal point.


Make sure the RefreshCache Resource is not set a cacheable. If the CacheClear extra is installed, make sure it is set that way as well.

If the refresh process does not finish, there is likely a problem with the last resource it shows in the list. A syntax error in a snippet is a common cause. RefreshCache sets the error_reporting level to 0 to prevent that, but any fatal error will still crash things.

If you see a red (usually incomprehensible) error message in the progress box of the CMP. You can see the actual error in Dev. Tools. In Chrome, press Ctrl-shift-i to launch Dev. Tools. Reload the CMP page, click on the Network tag, and clear the log by clicking on the circle with the slash through it at the upper left of the Dev. Tools window. Then click on the "Refresh the Cache" button. When the error appears, click on the last line of the request list in the Dev. Tools window. Click on the "Headers" tab. You'll see the ID of the offending Resource near the end of the top line. (e.g., id=273). Then click on the "Response" tab. You should see the full error there, inside the HTML shown.

If there is no error, but the refresh process is not completed, view the RefreshCache Resource. You should see the offending Resource and its ID at the end of the list. If it's a Resource you no longer need, delete it and refresh the cache using the Manage menu. If you need to keep it, you can either fix it, or uncheck the "Cacheable" box on the "Settings" tab while editing the Resource so RefreshCache will skip it.

RefreshCache System Settings

Setting Description Default
refreshcache_request_delay Delay between cURL requests (in seconds); note that there is a built-in delay of about 1 second 0
refreshcache_log_all_errors Log all errors to MODX Error Log no
refreshcache_honor_hidemenu Do not refresh resources hidden from menus; default; yes 1
refreshcache_limit Maximum number of resources for getList to retrieve 0 (no limit)


My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be 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