Use code PERFMATTERS for an extra 10% off!
  1. Home
  2. Docs
  3. General
  4. Filters to further customize Perfmatters

Filters to further customize Perfmatters

Below is a list of all the filters available in Perfmatters. These allow you to further customize the plugin. If you need an easy way to add a filter, we recommend the free WPCode plugin. Check out this article on how to add PHP to your WordPress site.

JavaScript

CSS

Preloading

Lazy loading

CDN

Core

Miscellaneous

perfmatters_after_local_analytics

The perfmatters_after_local_analytics action hook will fire directly after our inline local analytics script prints, so you could echo out a custom script if you need to fire additional events.

add_action('perfmatters_after_local_analytics', function() {
	echo '<script>
		//custom script here
	</script>';
});

perfmatters_allow_buffer

The perfmatters_allow_buffer filter allows you to selectively disable the Perfmatters output buffer from running entirely.

if(strpos($_SERVER['REQUEST_URI'], 'endpoint/')) {
	add_filter('perfmatters_allow_buffer', '__return_false');
}

perfmatters_buffer_excluded_extensions

The perfmatters_buffer_excluded_extensions filter allows you to modify the excluded extensions list for the buffer. In the example below, we remove .php from the excluded extensions and allow the buffer to run on .php URLs.

add_filter('perfmatters_buffer_excluded_extensions', function($extensions) {
  if(($key = array_search('.php', $extensions)) !== false) {
    unset($extensions[$key]);
  }
  return $extensions;
});

perfmatters_cache_path

The perfmatters_cache_path filter allows you to change the default cache path (cache) to a custom directory inside wp-content. This is used for features such as Remove Unused CSS and Local Google Fonts. Some hosting providers have more restrictive permissions, such as Pantheon. In the example below, we are changing the cache path to uploads/cache to ensure everything works properly. 

add_filter('perfmatters_cache_path', function($path) {
    return 'uploads/cache';
});

perfmatters_cdn

The perfmatters_cdn filter allows you to manipulate the CDN rewrite feature in Perfmatters. Below is an example of how to turn off the CDN rewrite selectively for pages only.

add_filter('perfmatters_cdn', function($cdn) {
  if(is_singular('page')) {
    return false;
  }
  return $cdn;
});

perfmatters_cdn_extensions

The perfmatters_cdn_extensions filter allows you to exclude certain file types from being rewritten to the CDN. Below is an example of excluding JS files.

add_filter('perfmatters_cdn_extensions', function($extensions) {
  if(($key = array_search('js', $extensions)) !== false) {
    unset($extensions[$key]);
  }
  return $extensions;
});

perfmatters_critical_image_exclusions

The perfmatters_critical_image_exclusions filter allows you to exclude an image from being picked up by the preload critical images feature.


add_filter('perfmatters_critical_image_exclusions', function($exclusions) {
   $exclusions[] = 'example.png';
   return $exclusions;
 });

perfmatters_critical_image_parent_exclusions

The perfmatters_critical_image_parent_exclusions filter allows you to exclude any image found inside a parent element from being considered for a critical image preload.

add_filter('perfmatters_critical_image_parent_exclusions', function($exclusions) {
  $exclusions[] = 'example-div-class';
  return $exclusions;
});

perfmatters_css_background_selectors

The perfmatters_css_background_selectors filter allows you to add CSS Background selectors for containers for which you want to lazy load background images.

add_filter('perfmatters_css_background_selectors', function($selectors) {
	$selectors[] = 'example-div-class';
	return $selectors;
});

perfmatters_defer_jquery

The perfmatters_defer_jquery filter allows you to manipulate the deferral of jQuery. Below is an example of preventing jQuery from being deferred on single posts of any post type.

add_filter('perfmatters_defer_jquery', function($bool) {
  if(is_singular()) {
	return false;
  }
  return $bool;
});

perfmatters_defer_js

The perfmatters_defer_js filter allows you to manipulate JS deferral. Below is an example of how to turn off defer on pages only.

add_filter('perfmatters_defer_js', function($defer) {
      if(is_singular('page')) {
        return false;
    }
    return $defer;
});

perfmatters_defer_js_exclusions

The perfmatters_defer_js_exclusions filter allows you to change JS deferral exclusions in different areas. For example, you could exclude multiple scripts from JS deferral, but only on single posts.

add_filter('perfmatters_defer_js_exclusions', function($exclusions) {
  if(is_single()) {
	$exclusions[] = 'hooks.min.js';
  	$exclusions[] = 'i18n.min.js';
  }
  return $exclusions;
});

perfmatters_delayed_scripts

The perfmatters_delayed_scripts filter allows you to manipulate your delayed scripts. For example, you could exclude a specific script from being delayed on a desktop device.

add_filter('perfmatters_delayed_scripts', function($scripts) {
     if(($key = array_search('name_of_your_script', $scripts)) !== false) {
         if(!wp_is_mobile()) {
             unset($scripts[$key]);
         }
     }
     return $scripts;
 });

perfmatters_delay_js

The perfmatters_delay_js filter is for turning your delayed scripts on or off entirely. For example, you could turn off delay only on pages. 

add_filter('perfmatters_delay_js', function($delay) {
      if(is_singular('page')) {
        return false;
    }
    return $delay;
});

perfmatters_delay_js_behavior

The perfmatters_delay_js_behavior filter allows you to manipulate the Delay JS behavior. For example, you could force Delay All JS behavior on single posts.

add_filter('perfmatters_delay_js_behavior', function($behavior) {
  
  if(is_singular('post')) {
	$behavior = 'all';
  }

  return $behavior;
});

perfmatters_delay_js_delay_click

The perfmatters_delay_js_delay_click filter allows you to disable the click delay if you are manually excluding the necessary JavaScript for interactive elements.

add_filter('perfmatters_delay_js_delay_click', '__return_false');

perfmatters_delay_js_exclusions

The perfmatters_delay_js_exclusions filter allows you to manipulate where your exclusions are running. For example, perhaps you’re using the Delay All Scripts feature along with WooCommerce and need to exclude some JavaScript for the gallery on the single product post type to function. You might not want those exclusions to impact the performance of your entire site, as jQuery can be quite heavy. With the filter, you could ensure the JavaScript is only excluded on the single product post type. 

add_filter('perfmatters_delay_js_exclusions', function($exclusions) {
	if(is_singular('product')) {
		$exclusions[] = 'jquery.min.js';
		$exclusions[] = 'flexslider';
		$exclusions[] = 'single-product.min.js';
		$exclusions[] = 'slick';
		$exclusions[] = 'functions.min.js';
		$exclusions[] = 'waypoint';
	}
	return $exclusions;
});

Here is another example using SureCart, if you wanted to exclude it from Delay JS exclusions, but only when the URL contains /buy/.

<?php 
add_filter('perfmatters_delay_js_exclusions', function($exclusions) {
	if(strpos($_SERVER['REQUEST_URI'], 'buy/')) {
		$exclusions[] = 'surecart';
		$exclusions[] = 'hooks.min.js';
		$exclusions[] = 'i18n.min.js';
	}
	return $exclusions;
});

perfmatters_delay_js_fastclick

The perfmatters_delay_js_fastclick filter allows you to change where FastClick is loading. For example, you could turn FastClick off on single pages.

add_filter('perfmatters_delay_js_fastclick', function($bool) {

  if(is_page()) {
    return false;
  }

  return $bool;
});

perfmatters_delay_js_timeout

The perfmatters_delay_js_timeout filter allows you to manipulate the JS delay timeout feature. For example, you could change the delay timeout to 7 seconds instead of the automatic 10 seconds. However, make sure not to set the timeout value too short, otherwise the JS delay feature won’t work properly. Remember, 99% of the time everything will fire on user interaction regardless. 

add_filter('perfmatters_delay_js_timeout', function($timeout) {
    return '7';
});

Here is another example where you could change the delay timeout to 7 seconds for pages only.

add_filter('perfmatters_delay_js_timeout', function($timeout) {

    if(is_singular('page')) {
        $timeout = '7';
    }

    return $timeout;
});

perfmatters_disable_woocommerce_scripts

The perfmatters_disable_woocommerce_scripts filter gives you more control over the Disable WooCommerce Scripts feature. For example, you could exclude a specific page from the script disables.

add_filter('perfmatters_disable_woocommerce_scripts', function($boolean) {
	if(is_page(123)) {
		return false;
	}
	return $boolean;
});

perfmatters_exclude_leading_images

The perfmatters_exclude_leading_images filter allows you to change the number of leading images that are excluded from lazy loading. For example, the following will set the Exclude Leading Images option to 3 on single posts or custom post types.

add_filter('perfmatters_exclude_leading_images', function($boolean) {
    if(is_singular()) {
      return 3;
    }
      return $boolean;
});

perfmatters_fade_in_speed

The perfmatters_fade_in_speed filter allows you to adjust the fade in transition speed in ms (default is 500). For example, you could change the speed to 1000 ms.

add_filter('perfmatters_fade_in_speed', function($speed) {
  return 1000; //speed in ms
});

perfmatters_get_current_ID

In some cases, you may want to add some additional logic of your own depending on the configuration of your site to ensure that the Script Manager is grabbing the correct ID for all of your posts. The perfmatters_get_current_ID filter allows you to modify and return a different value based on whatever you want.

function perfmatters_filter_current_ID($currentID) {

     $currentID = 123;

     return $currentID;
}
add_filter('perfmatters_get_current_ID', 'perfmatters_filter_current_ID');

perfmatters_image_dimensions_exclusions

The perfmatters_image_dimensions_exclusions filter allows you to exclude specific images from being checked for missing dimensions. In the example below, we exclude both a specific image and an entire image class.

add_filter('perfmatters_image_dimensions_exclusions', function($exclusions) {
  $exclusions[] = 'example-image.jpg';
  $exclusions[] = 'example-image-class';
  return $exclusions;
});

perfmatters_is_woocommerce

The perfmatters_is_woocommerce filter allows you to disable the WooCommerce check, so all optimizations would run on WooCommerce pages. You could configure your own function and logic for what is considered WooCommerce.

add_filter('perfmatters_is_woocommerce', '__return_false');

perfmatters_lazy_elements

The perfmatters_lazy_elements filter allows you to manipulate the lazy elements feature in Perfmatters. Below is an example of how to disable lazy elements entirely on single posts.

add_filter('perfmatters_lazy_elements', function($bool) {
	if(is_single()) {
		return false;
	}
	return $bool;
});

perfmatters_lazy_element_selectors

The perfmatters_lazy_element_selectors filter allows you to pass custom selectors to the element selectors option that will be used when determining which elements will be lazy loaded.

add_filter('perfmatters_lazy_element_selectors', function($selectors) {
	$selectors[] = 'div-background-class';
  	return $selectors;
});

perfmatters_lazyload

The perfmatters_lazyload filter allows you to manipulate the lazy loading feature in Perfmatters. Below is an example of how to disable all lazy loading specifically on pages only.

add_filter('perfmatters_lazyload', function($lazyload) {
    if(is_singular('page')) {
      return false;
    }
    return $lazyload;
});

perfmatters_lazyload_exclude_attributes

The perfmatters_lazyload_exclude_attributes filter helps you exclude images from lazy loading that might be harder to access and manipulate directly. It lets you add any attributes or portions of attributes that are specific to the image in question.

In the example below, we are targeting any images that contain either the title='Perfmatters' attribute or the partial class=’size-full attribute. This is simply a string match, so any portion of any attribute should work, it just needs to be an exact match for the image or images you are wanting to exclude.

function perfmatters_lazyload_exclude_attributes($attributes) {
     $attributes[] = "title='Perfmatters'";
     $attributes[] = "class='size-full";
     $attributes[] = "class='skip-lazy";

     return $attributes;
}
add_filter('perfmatters_lazyload_excluded_attributes', 'perfmatters_lazyload_exclude_attributes');

Here is an example of an exclusion based on an image file name match.

function perfmatters_lazyload_exclude_attributes($attributes) {
     $attributes[] = 'src="https://domain.com/image.png"';

     return $attributes;
}
add_filter('perfmatters_lazyload_excluded_attributes', 'perfmatters_lazyload_exclude_attributes');

perfmatters_lazyload_force_attributes

The perfmatters_lazyload_force_attributes filter can be used the same as in the excluded attributes example above, but when an element contains one of the included attributes, our lazy loader will skip checking that item for exclusions and continue attempting to lazy load that element.

function perfmatters_lazyload_force_attributes($attributes) {
     $attributes[] = "title='Perfmatters'";
     $attributes[] = "class='size-full";

     return $attributes;
}
add_filter('perfmatters_lazyload_forced_attributes', 'perfmatters_lazyload_force_attributes');

perfmatters_lazyload_noscript

The perfmatters_lazyload_noscript filter allows you to disable the <noscript> tags that get printed out below lazy loaded elements with a copy of the original element.

add_filter('perfmatters_lazyload_noscript', '__return_false');

perfmatters_lazyload_parent_exclusions

The perfmatters_lazyload_parent_exclusions filter allows you to add selectors for parent containers that you want to target and exclude any images they contain from lazy loading.

add_filter('perfmatters_lazyload_parent_exclusions', function($exclusions) {
	$exclusions[] = 'example-div-class';
	return $exclusions;
});

perfmatters_lazyload_youtube_autoplay

The perfmatters_lazyload_youtube_autoplay filter allows you to disable the autoplay parameter being added to the YouTube embed that is generated when the preview thumbnail is clicked. This can help if you need to track view counts from the embed.

add_filter('perfmatters_lazyload_youtube_autoplay', '__return_false');

perfmatters_lazyload_youtube_thumbnail_resolution

The perfmatters_lazyload_youtube_thumbnail_resolution filter allows you to change the quality of the thumbnail for YouTube. By default, a low-resolution image is pulled from YouTube, but you can change it to a different quality.

add_filter('perfmatters_lazyload_youtube_thumbnail_resolution', function($resolution) {
return 'maxresdefault';
});

There are four different thumbnail qualities you can choose from:

  • default: 120px by 90px (low-resolution)
  • mqdefault: 320px by 180px
  • hqdefault: 480px by 360px (this is the default)
  • sddefault: 640px by 480px
  • maxresdefault: 1280px by 720px (high-resolution)

Keep in mind that maxresdefault is not always available unless you upload a custom thumbnail to your YouTube video.

You can also use the wp_is_mobile function to show low-resolution images on mobile devices while showing high-resolution thumbnails on a desktop.

add_filter('perfmatters_lazyload_youtube_thumbnail_resolution', function($resolution) {
if(!wp_is_mobile()) {
$resolution = 'maxresdefault';
}
return $resolution;
});

perfmatters_lazyload_threshold

The perfmatters_lazyload_threshold filter allows you to change the viewport threshold for lazy loading. It accepts px or %. You can also change this property in the lazy loading section in the Perfmatters plugin settings.

add_filter('perfmatters_lazyload_threshold', function($threshold) {
 return '500px';
});

perfmatters_leading_image_exclusions

The perfmatters_leading_image_exclusions filter allows you to exclude an image from being picked up by the exclude leading images feature.

add_filter('perfmatters_leading_image_exclusions', function($exclusions) {
   $exclusions[] = 'example-image-class';
   return $exclusions;
 });

perfmatters_leading_image_parent_exclusions

The perfmatters_leading_image_parent_exclusions filter allows you to exclude any image found inside a parent element from being treated as a leading image in the DOM when that image is being considered for lazy loading.

add_filter('perfmatters_leading_image_parent_exclusions', function($exclusions) {
    $exclusions[] = 'mobile-menu';
    return $exclusions;
});

perfmatters_local_stylesheet_url

The perfmatters_local_stylesheet_url filter allows you to specify the root URL that is used for your stylesheets. By default, we check for the site URL, but sometimes this won’t match if there is a CDN rewrite happening outside of our plugin.


add_filter('perfmatters_local_stylesheet_url', function($url) {
    return 'https://cdn.example.com/';
});

perfmatters_login_url

The perfmatters_login_url filter can be used to selectively disable the custom login URL functionality in a specific location or endpoint.

add_filter('perfmatters_login_url', function($bool) {
  if(strpos($_SERVER['REQUEST_URI'], '?excludeme=true') !== false) {
    return false;
  }
  return $bool;
});

perfmatters_minify_css

The perfmatters_minify_css filter can be used to control the Minify CSS feature. For example, you could turn it off on single pages.

add_filter('perfmatters_minify_css', function($bool) {
      if(is_singular('page')) {
        return false;
    }
    return $bool;
});

perfmatters_minify_css_exclusions

The perfmatters_minify_js_exclusions filter can be used to modify the Minify CSS exclusions. For example, you exclude a specific CSS file from minification only on single posts.

add_filter('perfmatters_minify_css_exclusions', function($exclusions) {
  if(is_single()) {
      $exclusions[] = 'example.css';
  }
  return $exclusions;
});

perfmatters_minify_js

The perfmatters_minify_js filter can be used to control the Minify JavaScript feature. For example, you could turn it off on single pages.

add_filter('perfmatters_minify_js', function($bool) {
      if(is_singular('page')) {
        return false;
    }
    return $bool;
});

perfmatters_minify_js_exclusions

The perfmatters_minify_js_exclusions filter can be used to modify the Minify JavaScript exclusions. For example, you exclude a specific JavaScript file from minification only on single posts.

add_filter('perfmatters_minify_js_exclusions', function($exclusions) {
  if(is_single()) {
      $exclusions[] = 'example.js';
  }
  return $exclusions;
});

perfmatters_minify_threshold

The perfmatters_minify_threshold filter can be used to turn off the size threshold check when deciding to serve a minified vs original file. An example where you may want to turn the threshold check off is if you have a lot of stylesheets with background images that will then be encoded inline when minified to prevent additional requests, resulting in a larger minified file size.

add_filter('perfmatters_minify_threshold', '__return_false');

perfmatters_page_builders

The perfmatters_page_builders filter gives you more control over which query string parameters get excluded from optimizations. For example, you could add your own unique page builder parameter.

add_filter('perfmatters_page_builders', function($page_builders) {
  $page_builders[] = 'custom-builder';
  return $page_builders;
});

perfmatters_preload_critical_images

The perfmatters_preload_critical_images filter allows you to change the number of images picked up when using the preload critical images feature. Below is an example where we only preload two images on pages.

add_filter('perfmatters_preload_critical_images', function($critical_images) {
  if(is_page()) {
    return 2;
  }
  return $critical_images;
});

perfmatters_preloads

The perfmatters_preloads filter allows you to manipulate your preloads. For example, you could remove a specific preload from printing.

add_filter('perfmatters_preloads', function($preloads) {
   foreach($preloads as $key => $preload) {    
     if($preload['url'] == 'https://example.com/style.css') {
       //custom code
       unset($preloads[$key]);
     }
   }
   return $preloads;
 });

Here are a few examples of how to preload different resources (CSS, JS, WOFF2, JPG).

add_filter('perfmatters_preloads', function($preloads) {
  	$preloads[] = array(
	  'as' => 'style',
	  'url' => 'https://example.com/style.css'
   	);
  	$preloads[] = array(
	  'as' => 'script',
	  'url' => 'https://example.com/script.js'
   	);
  	$preloads[] = array(
	  'as' => 'font',
	  'url' => 'https://example.com/font.woff2'
   	);
	$preloads[] = array(
	  'as' => 'image',
	  'url' => 'https://example.com/image.jpg'
   	);
   return $preloads;
});

perfmatters_preloads_array

The perfmatters_preloads_array filter allows you to access the preloads that Perfmatters will print for the current URL as a data array for use in custom code.

add_filter('perfmatters_preloads_array', function($preloads) {
  //use $preloads array data
});

perfmatters_preloads_ready

The perfmatters_preloads_ready filter allows you to intercept the array of preload tag HTML that is about to be added to the DOM and modify it if needed.

The below example loops through the preloads array and uses RegEx to add a media query to all of the preloads except for the first one and prevent them from being preloaded at smaller resolutions.

add_filter('perfmatters_preloads_ready', function($preloads) {
	if(!empty($preloads) && is_array($preloads)) {
		foreach($preloads as $index => $preload) {
		   	if($index < 1) {
				continue;
		  	}
			$new_preload = preg_replace('#media=([\'"]).+?\1#', '', $preload);
        	$new_preload = str_replace('<link', '<link media="(min-width: 769px)"', $new_preload);
			$preloads[$index] = $new_preload;
		}
	}
	return $preloads;
});

perfmatters_remove_unused_css

You can use the perfmatters_remove_unused_css filter to change where unused CSS is removed on your site. Below is an example of turning unused CSS off only on pages.

add_filter('perfmatters_remove_unused_css', function($boolean) {
	if(is_page()) {
	  return false;
	}
  	return $boolean;
});

perfmatters_rest_api_exceptions

The perfmatters_rest_api_exceptions filter allows you to add custom route exceptions for plugins or services that might need to connect to the WordPress Rest API.

add_filter('perfmatters_rest_api_exceptions', function($exceptions) {
  $exceptions[] = 'custom-route1';
  $exceptions[] = 'custom-route2';
  return $exceptions;
});

perfmatters_rucss_async_stylesheets

The perfmatters_rucss_async_stylesheets filter allows you to programmatically set specific stylesheets that have already been excluded from used CSS to load asynchronously.

add_filter('perfmatters_rucss_async_stylesheets', function($stylesheets) {
    $stylesheets[] = 'style.css';
    return $stylesheets;
});

perfmatters_rucss_excluded_selectors

The perfmatters_rucss_excluded_selectors filter allows you to pass custom CSS selectors to the Excluded Selectors option that will be used when determining which elements can be safely removed when generating Used CSS.

add_filter('perfmatters_rucss_excluded_selectors', function($selectors) {
	$selectors[] = '.wp-block-column';
  	return $selectors;
});

perfmatters_rucss_excluded_stylesheets

The perfmatters_rucss_excluded_stylesheets filter allows you to programmatically exclude stylesheets from being included when generating Used CSS. 

add_filter('perfmatters_rucss_excluded_stylesheets', function($stylesheets) {
    $stylesheets[] = 'style.css';
      return $stylesheets;
});

perfmatters_script_manager_locale

The perfmatters_script_manager_locale filter allows you to change which language is used for the Script Manager UI, regardless of the default setting in WordPress. For example, you could force the Script Manager to use English, even if the site language is different.

add_filter('perfmatters_script_manager_locale', function($locale) {
  return 'en_US';
});

perfmatters_used_css

The perfmatters_used_css filter is primarily for third-party plugin and theme developers. It can be used to manipulate the final generated Used CSS output before it’s saved to a file. For example, when the URLs need to be adjusted for another function that is running.

add_filter('perfmatters_used_css', function($used_css_string) {
    //custom code here
    return $used_css_string;
});

perfmatters_used_css_below

The perfmatters_used_css_below allows you to move the used CSS to print right before the end </head> tag instead of right after the <title> tag. This can help if you run into any issues due to a large amount of inline used CSS and social media sites. For example, Facebook only checks for the og:image in the first 50 KB of the page source. If it can’t reach your meta tags, you’ll get an “Inferred Property” error from the Facebook debugger. By moving your used CSS below the meta tags, it fixes the issue.

add_filter('perfmatters_used_css_below', '__return_true');

Related Articles

Updates

Changelog
Feature requests