-
Notifications
You must be signed in to change notification settings - Fork 86
FAQ: Developers
When you help us! :-) Localization is tricky and we're happy to work with those willing to support the WordPress community. We will most likely follow the trends of WordPress itself to determine which languages are addressed first.
"Page fragment cache" dynamically loads content (real-time) on your cached pages by parsing them for specific tags you manually embed. Despite the naming, this feature should not be misunderstood with "Fragment Cache", the premium feature. "Page fragment cache" is related to the parsing of templates. "Fragment Cache" adds more complex behaviors to a template/theme or plugin. It extends the transient API in WordPress to provide caching and purge policy management for fragments you manually create. It also enables fragment groups, defined by a plugin or theme, which include common operations to be cached using transients.
Page fragment cache cannot be used in combination with Page Cache mode Disk: Enhanced, because that mode will load the cached page directly from Apache or NginX. We recommend using Disk: Basic, which will run PHP to process the requests with the benefit of speeding up responses by loading a cached page instead of building the page from scratch.
W3TC will search for comments explained below and run the PHP code dynamically before sending it to the browser.
The page fragment cache feature is perfect to display things like the current date and time or content based on the visitor's session. To be able to use page fragment cache, you define a static variable in your wp-config.php file like define( 'W3TC_DYNAMIC_SECURITY', 'mysecurestring' );. Also add mfunc and mclude to Ignored comment stems: in the Minify settings if it is enabled.
You are then able to use the mfunc and mclude comments as a replacement of the PHP-tags like this:
<!-- mfunc mysecurestring -->
if (is_user_logged_in()) {
echo '<a href="logout">Logout</a>';
} else {
echo '<a href="login">Login</a>';
}
<!-- /mfunc mysecurestring -->
<!-- mclude mysecurestring -->path/to/file.php<!-- /mclude mysecurestring -->
You could also shorten it a little bit if you prefer one line of PHP code:
<!-- mfunc mysecurestring echo date('Y-m-d H:i'); --><!-- /mfunc mysecurestring -->
<!-- mclude mysecurestring path/to/file.php --><!-- /mclude mysecurestring -->
If you want to use plugin functions or WordPress functions, like is_user_logged_in() in the example above, you have to enable Late initialization: in the Page Cache settings. Other functions, like the ones you defined in your theme, are not available. They should be defined within the fragment to be able to use them.
Several constants are available for these purposes:
-
define('DONOTCACHEPAGE', true);Disables page caching for a given page. -
define('DONOTCACHEDB', true);Disables database caching for given page. -
define('DONOTMINIFY', true);Disables minify for a given page. -
define('DONOTCDN', true);Disables content delivery network for a given page. -
define('DONOTCACHEOBJECT', true);Disables object cache for a given page.
It's possible to empty the entire cache or simply purge the cache of a single post / page:
- Purge the entire cache of html content:
if (function_exists('w3tc_flush_posts')) {
w3tc_flush_posts();
}
- Purge a single post / page by passing it's ID:
if (function_exists('w3tc_flush_post')) {
w3tc_flush_post($post_id);
}
There are two ways change user agent groups, functions or filter.
Using functions:
$group_config = w3tc_get_user_agent_group($group_name); //name of the group
$group_config['theme'] = 'newtheme';
$group_config['redirect'] = '';
$group_config['agents'] = array(escaped_string, [...]);
$group_config['enabled'] = true;
w3tc_save_user_agent_group($group_name, $group_config['theme'], $group_config['redirect'], $group_config['agents'], $group_config['enabled']);
Using filter:
function my_w3tc_mobile_groups($w3tc_groups) {
// any operations
// clear all groups example
$w3tc_groups = array();
// delete all groups and add new example
$w3tc_groups = array(....);
// merge groups example:
$w3tc_groups = array_merge($w3tc_groups, array(
'good_browsers' => array(
'theme' => 'good_theme/good_theme',
'enabled' => true,
'redirect' => '',
'agents' => array('firefox', 'chrome')
),
'bad_browsers' => array(
'theme' => 'bad_theme/bad_theme',
'enabled' => true,
'redirect' => '',
'agents' => array('msie', 'opera')
)
));
return $w3tc_groups;
}
add_filter('w3tc_mobile_groups', 'my_w3tc_mobile_groups');
There are two ways change referrer groups, functions or filter.
Using functions:
$group_config = w3tc_get_referrer_group($group_name); //name of the group
$group_config['theme'] = 'newtheme';
$group_config['redirect'] = '';
$group_config['referrers'] = array(escaped_string, [...]);
$group_config['enabled'] = true;
w3tc_save_referrer_group($group_name, $group_config['theme'], $group_config['referrer'], $group_config['referrers'], $group_config['enabled']);
Using filters:
function my_w3tc_referrer_groups($w3tc_groups) {
// any operations
// clear all groups example
$w3tc_groups = array();
// delete all groups and add new example
$w3tc_groups = array(....);
// merge groups example:
$w3tc_groups = array_merge($w3tc_groups, array(
'search_referrers' => array(
'theme' => 'search_theme',
'enabled' => true,
'redirect' => '',
'referrers' => array('google\.com')
),
'other_referrers' => array(
'theme' => 'video_theme',
'enabled' => true,
'redirect' => '',
'referrers' => array('youtube\.com')
)
));
return $w3tc_groups;
}
add_filter('w3tc_referrer_groups', 'my_w3tc_referrer_groups');</pre>
Define APP_REQUEST in wp-config.php for example:
if ($_SERVER['REQUEST_URI'] == '/my-specific-page/') {
define('APP_REQUEST', 'true');
}
Functions required for deleting and reloading over HTTP is found in inc/w3-total-cache-api.php.
Call w3tc_opcache_flush_file( true ) to reload file.
Call w3tc_opcache_flush( true ) to flush all files.
To do it locally with WP-CLI:
Call wp w3-total-cache opcache_flush_file local file1
Call wp w3-total-cache opcache_flush local
Refer to w3-total-cache/extensions/GenesisAdmin.php to see how to create an extension by example.
// Adding a basic function. See GenesisAdmin.php for how to setup settings screen.
add_filter('w3tc_extensions', 'custom_extension');
function custom_extension($extensions) {
$extensions['some.theme'] = array (
'name' => 'Custpom Framework Extension',
'author' => 'Bluw Widgets',
'description' => 'Adds specific caching capabilities.',
'author_uri' => 'http://example.com',
'extension_uri' => 'http://example.com',
'extension_id' => 'some.theme',
'settings_exists' => false,
'version' => '0.1',
'enabled' => true,
'requirements' => array(),
'path' => 'your-plugin-folder/extensions/CustomExtension.php'
);
}
Fragment caching adds new functionality to the WordPress Transients API:
- Adds support for grouping transients both per blog and site wide
- Adds support for manual flushing of registered transient groups
- Adds support for action based flushing of registered transient groups
- Adds support for caching filters and actions
To make the plugin aware that you group transients see code examples below:
add_action('w3tc_register_fragment_groups', 'my_plugin_register_groups');
function my_plugin_register_groups() {
//blog specific group and an array of actions that will trigger a flush of the group
w3tc_register_fragment_group('my_plugin_', array('publish_post'), 3600);
//If using MultiSite Network/site wide specific group and an array of actions that will trigger a flush of the group
w3tc_register_fragment_group_global('my_plugin_global_', array('edit_site'), 3600);
}
function my_plugin_flush_group() {
//manually flush group.
w3tc_fragmentcache_flush_group('my_plugin_');
}
//Set transients
function on_some_event() {
if (false === get_transient('my_plugin_some_key'))
//my_plugin_ prefix is the group name we registered earlier
set_transient('my_plugin_some_key', 'blog specific value');
if (false === get_site_transient('my_plugin_some_key'))
//my_plugin_site_ prefix is the group name we registered earlier
set_site_transient('my_plugin_site_some_key', 'site wide specific value');
}
// Cache action example
add_action('theme_post_loop', 'cache_theme_post_loop_start',-999999999);
add_action('theme_post_loop', 'cache_theme_post_loop_end', 999999999);
/**
* Start outputbuffering
*/
function cache_theme_post_loop_start() {
w3tc_fragmentcache_start('example1', 'examples', 'theme_post_loop');
}
/**
* Store the output buffer .
*/
function cache_theme_post_loop_end() {
w3tc_fragmentcache_end('example1', 'examples', false);
}
// Cache filter example
add_filter('theme_filter', 'cache_theme_filter_start',-999999999);
add_filter('theme_filter', 'cache_theme_filter_end', 999999999);
/**
* Start filter buffering and return filter result
*/
function cache_theme_filter_start($data) {
return w3tc_fragmentcache_filter_start('example_filter1', 'examples', $hook, $data);
}
/**
* Store the filter result and return filter result.
*/
function cache_theme_filter_end($data) {
return w3tc_fragmentcache_filter_end('example_filter1', 'examples', $data);
}