Hooks

Lightify has a large hook surface, because performance work is site-specific and the settings screen cannot anticipate every theme. Where a setting takes an exclusion list, there is nearly always a filter that does the same job in code. Add these to your theme’s functions.php or a site-specific plugin.

Cache and purging

lightify_is_cacheable

The final say on whether a page is cached. Runs after Lightify’s own checks.

bool

required

string

add_filter('lightify_is_cacheable', function ($cacheable, $html) {
    // Never cache a page showing a personalized greeting.
    if (str_contains($html, 'data-personalized')) {
        return false;
    }

    return $cacheable;
}, 10, 2);

lightify_cached_page_html

Filters the HTML about to be written to the cache file. This is how Lightify’s own features inject into cached pages, in priority order.

string

required

This runs once per cache write, not per request, so anything you add here is served to every visitor of that page. Never inject anything user-specific.

lightify_cache_only_html

Like the above, but for content that should exist only in the cached copy and never in the live render. Lightify uses it to inject the web vitals collector, so the first uncached visitor is not measured.

string

required

lightify_cache_file_name

Filters the generated cache file name, which is how cache variants are keyed.

string

required

lightify_cache_mobile

Whether to write separate mobile rewrite rules.

bool

default:"false"

lightify_htaccess_rules

The rules Lightify writes to .htaccess.

string

required

lightify_auto_purge_urls

The URLs an automatic purge will clear, after a post is saved or similar.

array

required

add_filter('lightify_auto_purge_urls', function ($urls) {
    // Editing anything should also clear the sitemap.
    $urls[] = home_url('/sitemap.xml');

    return $urls;
});

Purge actions

Eight actions, one pair per purge type. Use :before to purge an external cache at the same time, :after to react once Lightify is done.

Action	Argument
`lightify_purge_url:before` / `:after`	`$url`
`lightify_purge_urls:before` / `:after`	`$urls`
`lightify_purge_pages:before` / `:after`	None
`lightify_purge_everything:before` / `:after`	None

add_action('lightify_purge_urls:before', function ($urls) {
    my_cdn_purge($urls);
});

lightify_preload_urls

What preloading visits after a purge.

array

required

add_filter('lightify_preload_urls', function ($urls) {
    // Warm the three templates that matter, not everything.
    return [home_url('/'), home_url('/shop/'), home_url('/pricing/')];
});

lightify_preload_delay

Seconds between preload requests. Raise it on constrained hosting.

float

default:"0.5"

lightify_serviceworker

The generated service worker source, before it is written.

string

required

A syntax error here stops the service worker registering, which disables browser caching site-wide. Append rather than rewrite, and check the result in Application > Service Workers.

lightify_offline_fallback_page

The page served when a visitor is offline and the request is not cached.

string

default:"/404/"

Asset optimizations

Each exclusion list on the settings screen has a matching filter. Use the filter when the exclusions are conditional, or when you want them in version control rather than in the database.

Filter	Excludes from
`lightify_exclude_from_css_minify`	CSS minification
`lightify_exclude_from_js_minify`	JavaScript minification
`lightify_exclude_from_js_defer`	Deferring
`lightify_exclude_from_js_delay`	Delaying
`lightify_exclude_from_rucss`	Unused CSS removal
`lightify_exclude_from_lazy_load`	Lazy loading

Each receives an array of keywords and returns one.

add_filter('lightify_exclude_from_js_delay', function ($exclusions) {
    $exclusions[] = 'consent-manager';

    return $exclusions;
});

lightify_minified_css

The minified CSS for one file, before it is written.

string

required

string

lightify_rucss_css

The CSS produced by unused CSS removal.

string

required

string

lightify_rucss_include_selectors

Selectors forced into the generated CSS, the code equivalent of the CSS Inclusions field.

array|string

required

string

add_filter('lightify_rucss_include_selectors', function ($selectors, $html) {
    // Keep modal styles on pages that can open one.
    if (str_contains($html, 'js-open-modal')) {
        $selectors[] = '.modal';
    }

    return $selectors;
}, 10, 2);

lightify_interaction_timeout

Seconds before delayed JavaScript runs even without interaction.

int

default:"5"

Lazy rendering

Filter	Default	Controls
`lightify_lazy_render_skip_count`	`3`	Elements at the top left rendered normally
`lightify_lazy_render_limit`	`30`	Maximum elements lazy rendered per page
`lightify_lazy_render_exclude_keywords`	array	Elements never lazy rendered
`lightify_lazy_render_intrinsic_height`	`$height, $tag, $attrs`	The placeholder height reserved for an element

Raise the skip count if content below the fold on a short page flickers in.

Self-hosting

array

Which external domains are downloaded and served locally.

filter

Filters $content, $url_new, $extension before an external file is saved. Use it to rewrite URLs inside a downloaded stylesheet.

Images

Filter	Default	Controls
`lightify_webp_quality`	`82`	WebP output quality
`lightify_webp_images_per_page`	`50`	Images converted per page render
`lightify_lazy_load_above_fold_count`	`2`	Images excluded from lazy loading at the top
`lightify_lcp_scan_images`	`10`	Images examined when finding the LCP candidate
`lightify_lcp_min_image_area`	`50000`	Smallest area, in pixels, that can be the LCP element
`lightify_responsive_image_sizes`	`$sizes, $image`	The generated `sizes` attribute

// Higher quality WebP on a photography site.
add_filter('lightify_webp_quality', function () {
    return 90;
});

// A full-width hero means more images are above the fold.
add_filter('lightify_lazy_load_above_fold_count', function () {
    return 4;
});

Smart link prefetch

Filter	Default	Controls
`lightify_smart_link_prefetch_delay`	`90`	Milliseconds of hover before prefetching on desktop
`lightify_smart_link_prefetch_mobile_delay`	`450`	Milliseconds before prefetching on mobile
`lightify_smart_link_prefetch_max`	`12`	Maximum prefetches per page
`lightify_smart_link_prefetch_exclusions`	array	URL patterns never prefetched

add_filter('lightify_smart_link_prefetch_exclusions', function ($exclusions) {
    $exclusions[] = '/download/';

    return $exclusions;
});

Exclude any URL that acts on a plain GET. A prefetched link that deletes something, consumes a one-time token, or counts a download will fire without anyone clicking it.

Score alerts

Four filters shape the email, each receiving the old and new grade and score.

Filter	Controls
`lightify_score_alerts_recipient`	Where it is sent
`lightify_score_alerts_subject`	The subject line
`lightify_score_alerts_body`	The body
`lightify_score_alerts_headers`	The mail headers

add_filter('lightify_score_alerts_subject', function ($subject, $oldGrade, $newGrade) {
    return sprintf('[%s] Performance moved from %s to %s', get_bloginfo('name'), $oldGrade, $newGrade);
}, 10, 3);

lightify_web_vitals_updated

Fires when new vitals are stored. Use it to forward measurements to your own monitoring.

Integrations

Filter	Default	Controls
`lightify_varnish_enabled`	Detected from `X-Varnish`	Whether Varnish purging runs
`lightify_varnish_server`	`https://127.0.0.1`	Where `PURGE` requests are sent
`lightify_page_builder_template_post_types`	array	Post types treated as templates

Utilities

Filter	Default	Controls
`lightify_desktop_user_agent`	Lightify’s own	User agent used for desktop preload requests
`lightify_mobile_user_agent`	A Pixel 4 string	User agent used for mobile preload requests
`lightify_admin_js_vars`	array	Variables passed to the admin JavaScript

Settings and bootstrap

lightify_settings_update:before / :after

Fire around the settings write, both receiving $settings.

add_action('lightify_settings_update:after', function ($settings) {
    if ($settings['removeUnusedCss'] === 'on') {
        error_log('Lightify: unused CSS removal enabled.');
    }
});

lightify_pro_loaded

Fires once the Freemius SDK is initialized, before features are constructed.

Constants

Constant	Value
`LIGHTIFY_VERSION`	The plugin version string
`LIGHTIFY_FILE`	Absolute path to `lightify.php`
`LIGHTIFY_BASENAME`	Plugin basename
`LIGHTIFY_DIR_PATH`	Absolute path to the plugin directory
`LIGHTIFY_DIR_URL`	URL of the plugin directory
`LIGHTIFY_UPLOAD_DIR`	Absolute path to the plugin’s uploads directory
`LIGHTIFY_UPLOAD_URL`	URL of the plugin’s uploads directory
`LIGHTIFY_CACHE_DIR`	Absolute path to the page cache directory
`LIGHTIFY_CACHE_URL`	URL of the page cache directory

Getting started

Settings

Guides

Developer reference

Support

Cache and purging

lightify_is_cacheable

lightify_cached_page_html

lightify_cache_only_html

lightify_cache_file_name

lightify_cache_mobile

lightify_htaccess_rules

lightify_auto_purge_urls

Purge actions

lightify_preload_urls

lightify_preload_delay

lightify_serviceworker

lightify_offline_fallback_page

Asset optimizations

lightify_minified_css

lightify_rucss_css

lightify_rucss_include_selectors

lightify_interaction_timeout

Lazy rendering

Self-hosting

Images

Smart link prefetch

Score alerts

lightify_web_vitals_updated

Integrations

Utilities

Settings and bootstrap

lightify_settings_update:before / :after

lightify_pro_loaded

Constants

​Cache and purging

​lightify_is_cacheable

​lightify_cached_page_html

​lightify_cache_only_html

​lightify_cache_file_name

​lightify_cache_mobile

​lightify_htaccess_rules

​lightify_auto_purge_urls

​Purge actions

​lightify_preload_urls

​lightify_preload_delay

​lightify_serviceworker

​lightify_offline_fallback_page

​Asset optimizations

​lightify_minified_css

​lightify_rucss_css

​lightify_rucss_include_selectors

​lightify_interaction_timeout

​Lazy rendering

​Self-hosting

​Images

​Smart link prefetch

​Score alerts

​lightify_web_vitals_updated

​Integrations

​Utilities

​Settings and bootstrap

​lightify_settings_update:before / :after

​lightify_pro_loaded

​Constants

Cache and purging

lightify_is_cacheable

lightify_cached_page_html

lightify_cache_only_html

lightify_cache_file_name

lightify_cache_mobile

lightify_htaccess_rules

lightify_auto_purge_urls

Purge actions

lightify_preload_urls

lightify_preload_delay

lightify_serviceworker

lightify_offline_fallback_page

Asset optimizations

lightify_minified_css

lightify_rucss_css

lightify_rucss_include_selectors

lightify_interaction_timeout

Lazy rendering

Self-hosting

Images

Smart link prefetch

Score alerts

lightify_web_vitals_updated

Integrations

Utilities

Settings and bootstrap

lightify_settings_update:before / :after

lightify_pro_loaded

Constants