pantheon-systems / pantheon-advanced-page-cache
Requires (Dev)
- behat/behat: ^3.1
- behat/mink-extension: ^2.2
- behat/mink-goutte-driver: ^1.2
- pantheon-systems/pantheon-wordpress-upstream-tests: dev-master
- pantheon-systems/pantheon-wp-coding-standards: ^2.0
- pantheon-systems/wpunit-helpers: ^2.0
- phpcompatibility/php-compatibility: ^9.3
- phpunit/phpunit: ^9
- yoast/phpunit-polyfills: ^2.0
- dev-release
- 2.1.0
- 2.0.0
- v2.0.0-RC3
- v2.0.0-RC2
- v2.0.0-RC1
- 1.5.0
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.0
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- v1.1.1
- v1.1.0
- v1.0.0
- v0.3.1
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.5
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-rename-catalog-info-20240923
- dev-dependabot/npm_and_yarn/develop/sass-1.78.0
- dev-release-2.1.1
- dev-develop
- dev-pr-299
- dev-release-2.1.0
- dev-release-2.0.1
- dev-maybe-fix-npm-diff
- dev-npm-diff
- dev-purge_filters
This package is auto-updated.
Last update: 2024-09-23 20:47:38 UTC
README
贡献者: getpantheon, danielbachhuber, kporras07, jspellman, jazzs3quence, ryanshoover, rwagner00, pwtyler
标签: pantheon, cdn, cache
最低要求 6.4
测试到 6.6.1
稳定标签 2.1.0
许可证: GPLv2 或更新版
许可证URI: https://gnu.ac.cn/licenses/gpl-2.0.html
在更新内容时自动从 Pantheon Edge 清除相关页面。高 TTL。新鲜内容。访客无需等待。
描述
对于想要精细控制响应在边缘缓存中表示方式的网站,Pantheon 高级页面缓存是绝佳的选择。以下是插件工作原理的高级概述
- 当生成响应时,插件使用基于 WordPress 主要
WP_Query
对象的代理键来用标识符“标记”响应,这些标识符用于响应中的数据。有关包含您自己的代理键的“添加自定义键”部分。 - 当 WordPress 数据被修改时,插件触发了对应代理键的清除请求。
由于其代理键技术,Pantheon 高级页面缓存赋予了 WordPress 网站一个显著更精确的缓存清除机制,以及通常更高的缓存命中率。它甚至可以与 WordPress REST API 一起工作。
去创造美好吧!一旦你创造出了伟大的东西,给我们发送功能请求(或错误报告)。
安装
要安装 Pantheon 高级页面缓存,请按照以下步骤操作
- 使用 WordPress 仪表板从 WordPress.org 安装插件。
- 激活插件。
使用 WP-CLI 一行安装 Pantheon 高级页面缓存
wp plugin install pantheon-advanced-page-cache --activate
工作原理
Pantheon 高级页面缓存大量使用代理键,这使得响应可以被“标记”为可以在后续清除请求中使用的标识符。例如,主页响应可能包含带有以下键的 Surrogate-Key
标头
Surrogate-Key: front home post-43 user-4 post-41 post-9 post-7 post-1 user-1
类似地,对 /wp-json/wp/v2/posts
的 GET
请求可能包含带有以下键的 Surrogate-Key
标头
Surrogate-Key: rest-post-collection rest-post-43 rest-post-43 rest-post-9 rest-post-7 rest-post-1
由于缓存响应包含描述其中数据的元数据,因此代理键允许更灵活的清除行为,例如
- 当帖子更新时,清除帖子的 URL、主页、帖子出现的任何索引视图以及帖子存在的任何 REST API 端点上的缓存。
- 当作者更改他们的名字时,清除作者存档和任何他们所写的帖子上的缓存。
响应中的代理键数量有限,因此我们根据用户对正常 WordPress 网站的预期进行了优化。有关包含哪些键的详细信息,请参阅“发射键”部分,有关添加您自己的键的信息,请参阅随后的“添加自定义键”部分。
添加自定义键
默认情况下,Pantheon高级页面缓存根据对主WP_Query
查询对象的解释生成代理键。由于WordPress在页面渲染之前发送头信息,您需要使用pantheon_wp_main_query_surrogate_keys
过滤器来包含页面上存在的任何数据的额外代理键。
例如,要包含主页上渲染的侧边栏的代理键,您可以使用is_home()
模板标签来过滤键
/** * Add surrogate key for the featured content sidebar rendered on the homepage. */ add_filter( 'pantheon_wp_main_query_surrogate_keys', function( $keys ){ if ( is_home() ) { $keys[] = 'sidebar-home-featured'; } return $keys; });
然后,当侧边栏更新时,您可以使用pantheon_wp_clear_edge_keys()
辅助函数来发出针对代理键的特定清除事件
/** * Trigger a purge event for the featured content sidebar when widgets are updated. */ add_action( 'update_option_sidebars_widgets', function() { pantheon_wp_clear_edge_keys( array( 'sidebar-home-featured' ) ); });
类似地,要包含主页上查询的帖子的代理键,您可以在页面渲染之前预取帖子
/** * An example of pre-fetching a WP_Query to tag the * response with queried data. You'd use `papcx_wp_query()` * a second time within your template to use the data. */ add_filter( 'pantheon_wp_main_query_surrogate_keys', function( $keys ) { if ( is_home() ) { $query = papcx_wp_query( array( 'post_type' => 'page', ) ); foreach( $query->posts as $post ) { $keys[] = 'post-' . $post->ID; } } return $keys; }); /** * Register a 'papc-non-persistent' cache group to cache data * in a non-persistent manner. We only want data in this group * to be cached within the page request. */ add_action( 'init', function(){ wp_cache_add_non_persistent_groups( array( 'papc-non-persistent' ) ); }); /** * Helper function to instantiate a WP_Query object only * once per page request. * * @param array $args Arguments to pass to WP_Query. * @return WP_Query */ function papcx_wp_query( $args = array() ) { $cache_key = md5( serialize( $args ) ); // WP_Query object will be in cache the second time we use the function. $cache_value = wp_cache_get( $cache_key, 'papc-non-persistent' ); if ( false !== $cache_value ) { return $cache_value; } $query = new WP_Query( $args ); wp_cache_set( $cache_key, $query, 'papc-non-persistent' ); return $query; }
由于Pantheon高级页面缓存已经处理了WordPress帖子清除事件,因此不需要额外的pantheon_wp_clear_edge_keys()
调用。
最后,pantheon_wp_rest_api_surrogate_keys
过滤器允许您过滤REST API响应中存在的代理键。
需要更多功能?除了pantheon_wp_clear_edge_keys()
之外,您还可以使用两个额外的辅助函数
pantheon_wp_clear_edge_paths( $paths = array() )
- 清除一个或多个路径的缓存。pantheon_wp_clear_edge_all()
- 警告!权力越大,责任越大。清除整个缓存,但请明智地操作。
忽略特定的帖子类型
默认情况下,Pantheon高级页面缓存在清除其代理键方面非常积极。具体来说,每次调用wp_insert_post
(这可能包括添加或更新任何类型的帖子,包括私有帖子类型)时,它将清除包括home
、front
、404
和feed
在内的各种键。从1.5.0版本开始,我们有一个过滤器,允许传递一个要忽略的帖子类型的数组,在那些缓存被清除之前。默认情况下,忽略revision
帖子类型,但可以添加其他类型
/** * Add a custom post type to the ignored post types. * * @param array $ignored_post_types The array of ignored post types. * @return array */ function filter_ignored_posts( $ignored_post_types ) { $ignored_post_types[] = 'my-post-type'; // Ignore my-post-type from cache purges. return $ignored_post_types; } add_filter( 'pantheon_purge_post_type_ignored', 'filter_ignored_posts' );
这将防止在更新给定帖子类型时清除缓存。
使用过滤器设置缓存最大年龄
缓存最大年龄设置由Pantheon页面缓存管理页面控制。从2.0.0版本开始,默认情况下有三个缓存年龄选项——1周、1个月、1年。Pantheon高级页面缓存会自动清除更新和相关的帖子及页面的缓存,但您可能想覆盖缓存最大年龄值并设置它。在这种情况下,您可以使用添加到Pantheon MU插件1.4.0+中的pantheon_cache_default_max_age
过滤器。例如
add_filter( 'pantheon_cache_default_max_age', function() { return 10 * DAY_IN_SECONDS; } );
以这种方式过滤缓存最大年龄时,管理员选项被禁用,并显示一条通知。
根据nonce更新缓存最大年龄
前端创建的nonce(通常用于保护表单和其他数据)有一个生命周期,如果缓存最大年龄比nonce生命周期长,nonce可能会在缓存之前过期。为了避免这种情况,您可以使用pantheon_cache_nonce_lifetime
动作将pantheon_cache_default_max_age
设置得小于nonce生命周期。例如
do_action( 'pantheon_cache_nonce_lifetime' );
重要的是在适当的条件中包装您的do_action
,以确保仅在必要时调用操作,并且在不需要过滤缓存最大年龄的情况下不要过滤。这可能意味着只在您的代码的某些页面或上下文中运行。
WP-CLI命令
此插件实现了许多WP-CLI命令。所有命令都组成了wp pantheon cache
命名空间。
$ wp help pantheon cache
NAME
wp pantheon cache
DESCRIPTION
Manage the Pantheon Advanced Page Cache.
SYNOPSIS
wp pantheon cache <command>
SUBCOMMANDS
purge-all Purge the entire page cache.
purge-key Purge one or more surrogate keys from cache.
purge-path Purge one or more paths from cache.
使用wp help pantheon cache <command>
了解每个命令的更多信息。
调试
默认情况下,Pantheon 基础设施在向客户端提供服务响应之前,会移除 Surrogate-Key
响应头。该头的具体内容可以通过在请求中添加调试头的方式查看,即 Surrogate-Key-Raw
。
直接检查头的命令是 curl -I
。此命令会发送请求并仅显示响应头。添加 -H "Pantheon-Debug:1"
将导致在响应头中包含 Surrogate-Key-Raw
。完整的命令如下
curl -IH "Pantheon-Debug:1" https://scalewp.io/
使用 grep
将输出过滤到仅包含 Surrogate-Key-Raw
头
curl -IH "Pantheon-Debug:1" https://scalewp.io/ | grep -i Surrogate-Key-Raw
就是这样!
发出键和清除事件
传统视图上的发出键
主页 /
- 发出的代理键:
home
、front
、post-<id>
(主查询中的所有帖子)
单篇帖子 /2016/10/14/surrogate-keys/
- 发出的代理键:
single
、post-<id>
、post-user-<id>
、post-term-<id>
(所有分配给帖子的术语)
作者存档 /author/pantheon/
- 发出的代理键:
archive
、user-<id>
、post-<id>
(主查询中的所有帖子)
术语存档 /tag/cdn/
- 发出的代理键:
archive
、term-<id>
、post-<id>
(主查询中的所有帖子)
日存档 /2016/10/14/
- 发出的代理键:
archive
、date
、post-<id>
(主查询中的所有帖子)
月存档 /2016/10/
- 发出的代理键:
archive
、date
、post-<id>
(主查询中的所有帖子)
年存档 /2016/
- 发出的代理键:
archive
、date
、post-<id>
(主查询中的所有帖子)
搜索 /?s=<search>
- 发出的代理键:
search
、search-results
或search-no-results
、post-<id>
(主查询中的所有帖子)
未找到(404)
- 发出的代理键:
404
自定义帖子类型存档
- 发出的代理键:
archive
、post-type-archive
、<custom-post-type-name>-archive
、post-<id>
(主查询中的所有帖子)
REST API 端点上的发出键
帖子
/wp-json/wp/v2/posts
发出代理键:rest-post-collection
、rest-post-<id>
/wp-json/wp/v2/posts/<id>
发出代理键:rest-post-<id>
页面
/wp-json/wp/v2/pages
发出代理键:rest-page-collection
、rest-post-<id>
/wp-json/wp/v2/pages/<id>
发出代理键:rest-post-<id>
分类
/wp-json/wp/v2/categories
发出代理键:rest-category-collection
、rest-term-<id>
/wp-json/wp/v2/categories/<id>
发出代理键:rest-term-<id>
标签
/wp-json/wp/v2/tags
发出代理键:rest-post_tag-collection
、rest-term-<id>
/wp-json/wp/v2/tags/<id>
发出代理键:rest-term-<id>
评论
/wp-json/wp/v2/comments
发出代理键:rest-comment-collection
、rest-comment-post-<post-id>
、rest-comment-<id>
/wp-json/wp/v2/comments/<id>
发出代理键:rest-comment-post-<post-id>
、rest-comment-<id>
用户
/wp-json/wp/v2/users
发出代理键:rest-user-collection
、rest-user-<id>
/wp-json/wp/v2/users/<id>
发出代理键:rest-user-<id>
设置
/wp-json/wp/v2/settings
发出代理键:rest-setting-<name>
清除事件
不同的 WordPress 动作会导致清除不同的代理键,这里进行了说明。
wp_insert_post
/ transition_post_status
/ before_delete_post
/ delete_attachment
- 清除代理键:
home
、front
、404
、post-<id>
、user-<id>
、term-<id>
、rest-<type>-collection
、rest-comment-post-<id>
、post-type-archive
、<custom-post-type-name>-archive
- 受影响的视图:主页、单篇帖子、任何带有 404 头的页面、任何显示帖子的存档、作者存档、术语存档、REST API 集合和资源端点
clean_post_cache
- 清除代理键:
post-<id>
,rest-post-<id>
- 受影响的视图:单个帖子,REST API 资源端点
created_term
/ edited_term
/ delete_term
- 清除代理键:
term-<id>
,post-term-<id>
,rest-<taxonomy>-collection
- 受影响的视图:术语存档,任何分配了术语的帖子,REST API 集合和资源端点
clean_term_cache
- 清除代理键:
term-<id>
,rest-term-<id>
- 受影响的视图:术语存档,REST API 资源端点
wp_insert_comment
/ transition_comment_status
- 清除代理键:
rest-comment-collection
,rest-comment-<id>
- 受影响的视图:REST API 集合和资源端点
clean_comment_cache
- 清除代理键:
rest-comment-<id>
- 受影响的视图:REST API 资源端点
clean_user_cache
- 清除代理键:
user-<id>
,rest-user-<id>
- 受影响的视图:作者存档,任何用户是作者的帖子
updated_option
- 清除代理键:
rest-setting-<name>
- 受影响的视图:REST API 资源端点
术语的代理键
为具有大量分类(如具有大量全局属性的 WooCommerce 产品)的帖子设置代理键可能会导致查询速度变慢。可以使用以下过滤器跳过“产品”帖子类型的术语(或任何其他您认为合适的标准)的代理键:
```php function custom_should_add_terms($should_add_terms, $wp_query) { if ( $wp_query->is_singular( 'product' ) ) { return false; } return $should_add_terms; } add_filter('pantheon_should_add_terms', 'custom_should_add_terms', 10, 2);
其他过滤器
pantheon_apc_disable_admin_notices
从 2.0.0 版本开始,Pantheon 高级页面缓存显示有关您当前缓存最大年龄值的一组管理员通知。您可以使用 pantheon_apc_disable_admin_notices
过滤器禁用这些通知。
add_filter( 'pantheon_apc_disable_admin_notices', '__return_true' );
或者,将函数回调传递到 pantheon_apc_disable_admin_notices
过滤器中,允许您精确指定要禁用的通知,例如
add_filter( 'pantheon_apc_disable_admin_notices', function( $disable_notices, $callback ) { if ( $callback === '\\Pantheon_Advanced_Page_Cache\\Admin_Interface\\admin_notice_maybe_recommend_higher_max_age' ) { return true; } return $disable_notices; }, 10, 2 );
上述示例将仅禁用建议提高缓存最大年龄的管理员通知。
插件集成
Pantheon 高级页面缓存与以下 WordPress 插件集成:
贡献
有关贡献的信息,请参阅 CONTRIBUTING.md。
变更日志
2.1.0 (2024 年 8 月 8 日)
- 将连接到
pantheon_cache_default_max_age
过滤器的任何可调用的函数添加到在 WordPress 管理员中激活缓存最大年龄过滤器时显示的消息中。[#292] 这为在代码库中某处激活了过滤器的调试提供了一些上下文。如果使用匿名函数,则会在显示的消息中注明。 - 删除对
nonce_life
的挂钩,并用新操作(pantheon_cache_nonce_lifetime
,见文档)替换。[#293] 这错误地覆盖了任何管理员设置,并将某些站点的默认缓存最大年龄设置为始终为 23 小时(nonce 寿命减去 1 小时)。此解决方案要求开发人员在创建前端上的非ces时添加do_action
,但在所有其他情况下允许缓存设置按设计工作。
2.0.0 (2024 年 5 月 28 日)
- 增加了关于默认缓存最大年龄设置和推荐的新的管理员警报和站点健康测试 [#268, #271]. Pantheon GCDN 缓存最大年龄默认值已更新为1周,在 Pantheon MU 插件 中。更多信息,请参阅 发布说明。
- 在 Pantheon 环境中(带有 Pantheon MU 插件)使用时更新了 Pantheon 页面缓存管理员页面上的 UI ([#272])。此 UI 更改在 Pantheon MU 插件版本 1.4.3 可用时生效。
- 如果缓存最大年龄保存为旧默认值(600秒),则自动更新缓存最大年龄为推荐值(1周)。 [#269]
- 在前端创建非ces时,在
nonce_life
过滤器中添加钩子,将pantheon_cache_default_max_age
设置为小于非ces生存期,以避免非ces在缓存过期之前过期。 [#282] props @ryanshoover
1.5.0(2024年3月11日)
- 添加过滤器
pantheon_purge_post_type_ignored
,允许在清除缓存之前忽略一系列帖子类型 [#258] - 添加 wpunit-helpers 以运行/设置 WP 单元测试
1.4.2(2023年10月16日)
1.4.1(2023年8月8日)
- 将 REST API 响应头发送到结果而不是 REST 服务器 [#237]。Props @srtfisher & @felixarntz。
1.4.0(2023年8月1日)
1.3.0(2023年4月19日)
- 添加了对 WordPress 多站点的支持,这解决了在多站点安装中编辑一个子站点的帖子时,如果它包含具有相同 ID 的帖子,则清除其他站点的首页缓存的问题。[#228]
1.2.4(2023年4月13日)
- 为特定于存档的帖子类型存档页面(例如“作品集”)添加代理密钥,例如“作品集存档”,并在适当的情况下清除该存档。[#225]
1.2.3(2023年4月5日)
- 将测试升级到版本 6.2
1.2.2(2023年3月14日)
1.2.1(2023年2月23日)
1.2.0(2022年11月29日)
- 添加构建标签和部署到wp.org的Github Actions。添加CONTRIBUTING.md。[#203]
1.1.0(2022年11月1日)
- 挂钩到WPGraphQL以发出代理键[#199].
- 将插件集成部分添加到README
1.0.0(2020年3月2日)
- 插件稳定。
0.3.1(2019年10月27日)
0.3.0(2017年11月27日)
0.2.1(2017年10月25日)
- 确保使用
?_embed
发出正确的代理键[#103].
0.2.0(2017年8月10日)
- 自动修剪大型代理键列表,以防止Nginx和Varnish的header size限制。
0.1.5(2017年5月24日)
- 除非通过过滤器显式添加,否则禁用为管理员发出代理键。
0.1.4(2017年3月7日)
- 为RSS源发出
feed
代理键,并在创建、修改或删除帖子时清除。
0.1.3(2017年3月1日)
- 仅当设置时才访问帖子类型和分类的
$rest_base
属性,以防止错误通知。
0.1.2(2016年12月6日)
- 如果已删除
delete_others_posts
能力,则允许管理员清除特定页面的缓存。
0.1.1(2016年11月30日)
- 放弃设置UI,而是将其包含在Pantheon的WordPress上游中。
0.1.0(2016年11月23日)
- 初始发布。
升级通知
2.0.0
此版本需要最低WordPress版本为6.4.0。它使用站点健康检查和wp_admin_notices
函数来提醒用户新的缓存max-age默认设置和建议。插件仍将与早期版本兼容,但您将无法获得警报和站点健康检查的好处。
此版本还自动更新缓存最大年龄(在Pantheon 页面缓存设置中设置)为推荐值(1周),如果之前保存的是旧默认值(600秒)。如果缓存最大年龄设置为其他值(或根本未设置),则不会进行更改。管理界面将显示一次性通知,告知管理员此更改。
1.3.0
请注意,Pantheon 高级页面缓存 1.3.0 版本现在在 WordPress 多站点(WPMS)的键前加上博客 ID。对于已经在 WPMS 上安装此插件的用户,他们需要在设置页面点击“清除缓存”按钮以生成带前缀的键。