Advanced Aggregates

Last updated on

15 February 2024

Core benefits and features

AdvAgg for Drupal 8 has some significant differences from Drupal 7; instead of totally reworking asset handling, AdvAgg only applies some improvements. This is mostly because the core handling is much better. It is also better for compatibility with quite a few other modules such as http2_server_push.
Url query string to turn off AdvAgg for that request. ?advagg=0 will turn off file optimization if the user has the "bypass advanced aggregation" permission. ?advagg=-1 will completely bypass all of Advanced CSS/JS Aggregations modules and submodules. ?advagg=1 will enable Advanced CSS/JS Aggregation if it is currently disabled.
Button on the admin page for dropping a cookie that will turn off file optimization. Useful for theme development.
Gzip support. All optimized files can be pre-compressed into a .gz file and served from the server. This is faster then gzipping the file on each request.
Brotli support. All optimized files can be pre-compressed with the newer brotli compression algorithm; this often shows close to 30% improvements in file size vs gzip. Requires the brotli php extension is installed.
With various submodules substantially improved front end performance through minification of assets and other techniques can be achieved. Read more below.

Submodule Overview

AdvAgg comes with quite a few submodules to do various tasks. Most are compatible with the vast majority of other mods but some may have conflicts. If so those are noted here and more details in the module's full write-ups.

AdvAgg Cdn (advagg_cdn)

This module may have conflicts, but only with other CDN type modules.

Load CSS or JavaScript libraries from a public CDN; currently only supports jQuery and jQuery UI with either Google's or Microsoft's CDN.

AdvAgg CSS/JS Validator (advagg_validator)

Validate CSS and or JS files in your site through a few different validators.

AdvAgg External Minifier (advagg_ext_minify)

Minify CSS or JS through an otherwise unsupported method, with a configurable command line.

AdvAgg Minify CSS (advagg_css_minify)

Minify the CSS files using a 3rd party minifier; currently supports YUI (included) or the Core minification algorithm.

AdvAgg Minify JS (advagg_js_minify)

Compress the compiled JavaScript files using a 3rd party minifier; built in support for a number of minifiers.

AdvAgg Modifier (advagg_mod):

Depending on tweaks applied this module may cause compatibility issues with other modules.

Includes additional tweaks that may not work for all sites such as: - Force preprocessing for all CSS/JS. - Add defer tag to all JS. - Defer CSS loading using rel=preload and JavaScript Polyfill. - Add async tag to all or only local JavaScript.

AdvAgg Old IE Compatibility Enhancer (advagg_old_ie_compatibility)

This module may have conflicts with other modules if it is enabled.

Includes additional functionality to improve Drupal compatibility with old versions of Internet Explorer (6-9).

Configuration

The Advagg settings page is located at: admin/config/development/performance/advagg.

Global Options

Enable Advanced Aggregation: You can quickly temporarily disable all AdvAgg functionality by un-checking this. For testing purposes, see also Testing AdvAgg. [Default: enabled]
Use DNS Prefetch for external CSS/JS: If enabled places prefetch tags near the top of your html to trigger DNS look-ups as soon as possible on load. [Default: disabled]
Server Config: Server configuration options for AdvAgg. Mostly only available on Apache server. For more details see Server Settings.
Include Cache-Control: immutable in generated .htaccess files. Apache only include directives in .htaccess to send Cache-Control Immutable headers for all optimized files. Only supported on Edge 15+ and Firefox 49+. In other browsers, they will have no effect, so can be safely enabled. [Default: enabled]
AdvAgg Cache Settings: Development will scan all files for a change on every page load. Normal is fine for all use cases. Aggressive should be fine in almost all use cases. [Default: Normal]

Compression Options

Gzip [CSS/JS] Assets: If enabled, AdvAgg will create gzip compressed version of every file that is generated. This will then be served if the users' browser supports it instead of the uncompressed file saving time and bandwidth. [Default: enabled]
Brotli Compress [CSS/JS] Assets: Only selectable if the non standard PHP brotli extension is installed. If enabled, Advagg will create brotli compressed versions of every file that is generated. Moderately better compression ratios than Gzip, but lower server and browser support. [Default: disabled]

CSS Options

Combine CSS files by using media queries: If enabled, AdvAgg will add a media query wrapper to any file that needs it so that aggregation is more efficient. [Default: disabled]
Fix improperly set type: If type is external but does not start with http, https, or // change it to be type file. If type is file but it starts with http, https, or // change type to be external. [Default: enabled]

JS Options

Fix improperly set type: If type is external but does not start with http, https, or // change it to be type file. If type is file but it starts with http, https, or // change type to be external. [Default: enabled]
Do not change external to file if on same host: In rare cases, JS files may be on the same host but are actually still external such as served via a CDN. [Default: disabled]

CRON Options

Unless you have a good understanding of what you are trying to do, probably better to leave these alone. For best performance, setting up an external cron task is better than relying on Drupal's built in "poor man's cron".

Minimum amount of time between advagg_cron() runs: Set the minimum amount of time between advagg_cron runs. advagg_cron whenever you site cron runs, if less than the minimum time, will return before further processing. [Default: 1 day]
Delete aggregates modified more than a set time ago: Set how old to keep generated files for. Longer will have higher performance and with AdvAgg 8.x-3.x should have no negatives except for possibly wasted disk space from rarely used or changed files. [Default: 1 month]

Obscure Options

Convert absolute paths to protocol relative paths: Only applies to external files, this will change any http:// or https:// based urls to use //. [Default: enabled]
Convert http:// to https://: Also only applies to external files and is mutually incompatible with Convert absolute paths to protocol relative paths. [Default: disabled]
Use "Options +SymLinksIfOwnerMatch": On some rare hosting configurations the AdvAgg htaccess files need to use Options +SymLinksIfOwnerMatch instead of the more common Options +FollowSymlinks. [Default: disabled]

Information page

Located at admin/config/development/performance/advagg/info. This page provides debugging information. There are no configuration options here.

Hook Theme Info: Displays the preprocess_html order.
Core Asset Hooks Implemented by Modules: List modules implementing the various core asset hook functions. Note: if a module does not use these but is changing things with assets beyond adding/removing, there is a much greater chance that there may be conflicts with AdvAgg especially with some of the submodules.
Get information about an optimized file: Enter the name of an optimized file and get back an array of information about the file including its original name and location.

Operations page

Located at admin/config/development/performance/advagg/operations. This is a collection of commands to control the cache and manage testing of this module. In general this page is useful when troubleshooting some aggregation issues.

Aggregation Bypass Cookie: Toggle The "aggregation bypass cookie" for the current browser. If enabled will disable AdvAgg for the user for the period of time specified. It acts almost the same as adding ?advagg=0 to every URL.
Cron Maintenance Tasks: Remove All Stale Files: Scan all files in the css/js optimized directories and remove old files. See also Cron Options on the Configuration Page.

Drastic Measures

Clear All Caches: Remove all data stored in the advagg cache, and delete all optimized files.
Increment Global Counter: Force the creation of all new files with new names by incrementing a global counter.

Developing your site with Advanced Aggregates

With the new architecture, Advanced Aggregates is much more intelligent when in development. It will detect changed files, however, depending on settings it may not be instant. Also, repeatedly optimizing a file for every minor change when doing stylesheets or JavaScript isn't the most efficient option. So, what can you do? If just one site instance (questionable but budgets etc), you may want to just adjust the configuration to refresh caches a bit faster or disable AdvAgg temporarily while doing heavy development.

That will work but, there are a few other methods that will work better for some work flows especially if doing config import and export.

Temporarily Disabling AdvAgg

Via a settings.local.php. Often developers will disable core asset aggregation with config overrides or enable various core development features. You can do the same to disable AdvAgg. For example some users use the following lines:

// Disable Core CSS and JS aggregation and caching.
$config['system.performance']['cache']['page']['max_age'] = 0;
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

// Disable AdvAgg.
$config['advagg.settings']['enabled'] = FALSE;

Via main config page, un-check Enable Advanced Aggregates. This will take effect right away for all users.
Via the AdvAgg url parameter. Not as reliable depending on various system caches. To use, just append ?advagg=0 to your url.
Using the browser cookie function from the Operations page. Similar to the url parameter this isn't as good as the first 2 options.

Server Settings

AdvAgg can adjust configuration to improve performance for Apache servers. It does that through .htaccess files. There are reasons not to use .htaccess, however for most sites those aren't an important issue as it is a performance fine tuning issue. However for non-apache servers, .htaccess files don't work and in the case of Nginx, there is no equivalent. Instead Nginx has all such configuration within the server/vhost definition.

So if you're using Nginx read on for instructions on adding those to your vhost or server settings. All of the below snippets go within the server { } block in your config files.

Cache Control Immutable

The immutable cache control header is a fairly new header. Only Firefox & Edge currently support it as of September 2017. Browsers that don't support it will ignore so it is safe to enable.

To enable in nginx add the following to your server configuration:

location ~ ^/sites/.*/files/(css|js)/optimized { add_header Cache-Control 'public, max-age=31536000, immutable'; }

If you wanted this to also apply to agreggates as well as the individual AdvAgg optimized files, just removed the optimized from the location line.

Serving Compressed Assets.

On Apache, AdvaAgg handles this pretty well. On other servers, it doesn't however, if you've already configured your server to serve compressed assets from Drupal core, likely it'll just work. On the other hand, many Nginx default configurations may not be setup to serve static compressed assets.

Brotli

At this point in time, serving Brotli assets will still require you to build your Nginx server from source, with the Nginx Brotli module - doable but beyond the scope of this manual. Once you have that installed, configuring your vhost/server settings is very easy, just add the following:

location ~ ^/sites/.*/files/(css|js) { brotli_static on; }

Gzip

Serving Gzip assets also requires a seperate module to be enabled it is part of the main nginx code and there are distributions with it - for example on Ubuntu use apt-get install nginx-extras to install a prebuilt version, otherwise you can build your own custom version. See more details about the Nginx GZip Module Configuring your server setting is equally easy and almost identical to the Brotli configuration:

location ~ ^/sites/.*/files/(css|js) { gzip_static on; }

If you want to serve either Gzip or Brotli depending on the user's browser just use both declarations: vhost/server settings is very easy, just add the following:

location ~ ^/sites/.*/files/(css|js) { brotli_static on; gzip_static on; }

Tips & tricks

JavaScript Bookmarklet

You can use this JS code as a bookmarklet for toggling the AdvAgg URL parameter. See http://en.wikipedia.org/wiki/Bookmarklet for more details.

javascript:(function(){ var loc = document.location.href, qs = document.location.search, regex_off = /\&?advagg=-1/, goto = loc; if(qs.match(regex_off)) { goto = loc.replace(regex_off, ''); } else { qs = qs ? qs + '&advagg=-1' : '?advagg=-1'; goto = document.location.pathname + qs; } window.location = goto; })();

Configuration for a high Google PageSpeed score

Go to admin/config/development/performance/advagg - check "Combine CSS files by using media queries"

Ensure AdvAgg Modifier is enabled and go to admin/config/development/performance/advagg/mod - Under "Move JS to the footer" Select "All" - set "Enable preprocess on all JS/CSS" - set "Move JavaScript added by drupal_add_html_head() into drupal_add_js()" - Enable every checkbox under "Optimize JavaScript/CSS Ordering"

Ensure AdvAgg Minify JS is enabled and go to admin/config/development/performance/advagg/js-minify - Select JSMin if available; otherwise select JSMin+.