README

这是一个针对WordPress插件和主题的自定义更新检查器库。它允许您为商业插件、私有主题等添加自动更新通知和一键升级功能。您只需将插件/主题的详细信息放入JSON文件中，将该文件放置在您的服务器上，并将URL传递给库。库会定期检查URL，以查看是否有新版本可用，并在必要时向用户显示更新通知。

从用户的角度来看，它的工作方式与托管在WordPress.org上的插件和主题类似。更新检查器使用大多数WordPress用户熟悉的默认升级UI。

目录

• 入门指南
  • 自托管插件和主题
    • 如何发布更新
    • 注意事项
  • GitHub集成
    • 如何发布更新
    • 注意事项
  • BitBucket集成
    • 如何发布更新
  • GitLab集成
    • 如何发布GitLab更新
• 从4.x迁移
• 许可证管理
• 资源

入门指南

注意：在每个以下示例中，部分说明是创建更新检查器类的实例。建议您在plugins_loaded动作期间或任何钩子之外执行此操作。如果您仅在admin_*动作期间执行此操作，则更新对各种WordPress管理工具不可见；它们仅对登录用户在仪表板页面可见。

自托管插件和主题

1. 下载最新版本并将plugin-update-checker目录复制到您的插件或主题。

2. 转到examples子目录并打开适合您的项目类型的.json文件。用您的插件/主题详细信息替换占位符数据。

   • 插件示例

      {
      	"name" : "Plugin Name",
      	"version" : "2.0",
      	"download_url" : "https://example.com/plugin-name-2.0.zip",
      	"sections" : {
      		"description" : "Plugin description here. You can use HTML."
      	}
      }

     这是一个省略了可选字段的简化示例。有关支持的字段及其描述的完整列表，请参阅此表。

   • 主题示例

      {
      	"version": "2.0",
      	"details_url": "https://example.com/version-2.0-details.html",
      	"download_url": "https://example.com/example-theme-2.0.zip"
      }

     这是一个实际上显示所有主题相关字段的完整示例。version和download_url应该很容易理解。details_url键指定用户在点击更新通知中的“查看版本1.2.3详情”链接时将看到的页面。

3. 将JSON文件上传到公开可访问的位置。

4. 将以下代码添加到主插件文件或functions.php文件

   require 'path/to/plugin-update-checker/plugin-update-checker.php';
   use YahnisElsts\PluginUpdateChecker\v5\PucFactory;
   
   $myUpdateChecker = PucFactory::buildUpdateChecker(
   	'https://example.com/path/to/details.json',
   	__FILE__, //Full path to the main plugin file or functions.php.
   	'unique-plugin-or-theme-slug'
   );

   注意：如果您使用的是Composer自动加载器，则不需要显式require库。

如何发布更新

更改JSON文件中的version数字，并确保download_url指向最新版本。如果需要，更新其他字段。提示：您可以使用wp-update-server来自动化此过程。

默认情况下，库将每12小时检查指定的URL是否有更改。您可以通过点击“插件”页面上的“检查更新”链接（它位于“访问插件网站”链接旁边）来强制它立即检查。主题没有该链接，但您也可以像这样触发更新检查

1. 安装调试栏。
2. 点击管理栏中的“调试”菜单（也称为工具栏）。
3. 打开“PUC (your-slug)”面板。
4. 点击“立即检查”按钮。

注意事项

• 传递给 buildUpdateChecker 的第二个参数必须是主插件文件或主题目录中的任何文件的绝对路径。如果您按照“入门”说明进行操作，可以直接使用 __FILE__ 常量。

• 第三个参数，即别名，是可选的，但建议使用。在大多数情况下，别名应与您的插件目录名称相同。例如，如果您的插件位于 /wp-content/plugins/my-plugin，则将别名设置为 my-plugin。如果省略别名，更新检查器将使用主插件文件的名称作为别名（例如 my-cool-plugin.php → my-cool-plugin）。如果您的插件文件名通用（如 plugin.php），则可能导致冲突。

  这不会影响主题，因为PUC使用主题目录名称作为默认别名。不过，如果您计划在自己的代码中使用别名（例如，用于筛选更新或覆盖更新检查器行为），则明确设置它是个好主意。

GitHub集成

1. 下载最新版本并将plugin-update-checker目录复制到您的插件或主题。

2. 将以下代码添加到主插件文件或 functions.php

   require 'plugin-update-checker/plugin-update-checker.php';
   use YahnisElsts\PluginUpdateChecker\v5\PucFactory;
   
   $myUpdateChecker = PucFactory::buildUpdateChecker(
   	'https://github.com/user-name/repo-name/',
   	__FILE__,
   	'unique-plugin-or-theme-slug'
   );
   
   //Set the branch that contains the stable release.
   $myUpdateChecker->setBranch('stable-branch-name');
   
   //Optional: If you're using a private repository, specify the access token like this:
   $myUpdateChecker->setAuthentication('your-token-here');

3. 仅插件：将按照 WordPress.org 插件 readme 标准 格式的 readme.txt 文件添加到您的存储库中。当用户点击“查看版本 1.2.3 详细信息”链接时，将显示此文件的 内容。

如何发布更新

此库支持在 GitHub 上发布更新的一两种不同方式。选择最适合您的工作流程的方式。

• GitHub 发布

  使用 GitHub 上的“发布”功能创建一个新发布。标签名称和发布标题不重要。描述是可选的，但如果您提供了描述，它将在用户点击“插件”页面上的“查看版本 x.y.z 详细信息”链接时显示。请注意，PUC 忽略标记为“这是预发布版”的发布。

  如果想要使用发布资产，在创建更新检查器实例后调用 enableReleaseAssets() 方法。

   $myUpdateChecker->getVcsApi()->enableReleaseAssets();

• 标签

  要发布版本 1.2.3，创建一个名为 v1.2.3 或 1.2.3 的新 Git 标签。就是这样。

  PUC 不要求严格遵循 SemVer。以下都是有效的标签名称：v1.2.3、v1.2-foo、1.2.3_rc1-ABC、1.2.3.4.5。然而，请注意，它无法智能地过滤 alpha/beta/RC 版本。如果这是问题，您可能想要使用 GitHub 发布或分支。

• 稳定分支

  将更新检查器指向一个稳定、生产就绪的分支。

   $updateChecker->setBranch('branch-name');

  PUC 将定期检查主插件文件或 style.css 中的 Version 标头，并在版本高于已安装版本时显示通知。

  注意：如果您将分支设置为 master（默认值），更新检查器将首先查找最近的发布和标签。如果没有找到其他合适的选项，它才会使用 master 分支。

注意事项

库将从以下部分中拉取发布/标签/分支的更新详细信息。

• 版本号
  • “版本”插件标题。
  • 最新的 GitHub 发布或标签名称。
• 变更日志
  • readme.txt 中的“变更日志”部分。
  • 以下文件之一：CHANGES.md、CHANGELOG.md、changes.md、changelog.md
  • GitHub 发布说明。
• 所需和测试的 WordPress 版本
  • readme.txt 中的“至少需要”和“已测试至”字段。
  • 以下插件标题：Required WP、Tested WP、Requires at least、Tested up to
• “最后更新”时间戳
  • 最新 GitHub 发布的创建时间戳。
  • 所选标签或分支的最新提交。
• 下载次数
  • 最新发布的 download_count 统计数据。
  • 如果您不使用GitHub发行版，将不会有下载统计信息。
• 其他插件详细信息 - 作者、主页URL、描述
  • readme.txt文件的“描述”部分。
  • 远程插件头部（即GitHub上的最新版本）。
  • 本地插件头部（即当前安装的版本）。
• 评分、横幅、截图
  • 不支持。

BitBucket集成

1. 下载最新版本并将plugin-update-checker目录复制到您的插件或主题。

2. 将以下代码添加到主插件文件或 functions.php

   require 'plugin-update-checker/plugin-update-checker.php';
   use YahnisElsts\PluginUpdateChecker\v5\PucFactory;
   
   $myUpdateChecker = PucFactory::buildUpdateChecker(
   	'https://bitbucket.org/user-name/repo-name',
   	__FILE__,
   	'unique-plugin-or-theme-slug'
   );
   
   //Optional: If you're using a private repository, create an OAuth consumer
   //and set the authentication credentials like this:
   //Note: For now you need to check "This is a private consumer" when
   //creating the consumer to work around #134:
   // https://github.com/YahnisElsts/plugin-update-checker/issues/134
   $myUpdateChecker->setAuthentication(array(
   	'consumer_key' => '...',
   	'consumer_secret' => '...',
   ));
   
   //Optional: Set the branch that contains the stable release.
   $myUpdateChecker->setBranch('stable-branch-name');

3. 可选：将格式符合WordPress.org插件readme标准的readme.txt文件添加到您的仓库中。对于插件，当用户点击“查看版本1.2.3详情”链接时，将显示此文件的 内容。

如何发布更新

BitBucket没有GitHub发行版的等价功能，因此过程略有不同。您可以使用以下任何一种方法

• 稳定标签头部

  如果您使用标签标记每个版本，则这是一种推荐的方法。将格式符合WordPress.org插件readme标准的readme.txt文件添加到您的仓库中。将“稳定标签”头部设置为表示最新发布的标签。示例

   Stable tag: v1.2.3
  

  标签不需要以“v”开头或遵循任何特定格式。只要它是一个有效的Git标签，您可以使用任何喜欢的名称。

  提示：如果您明确设置了稳定分支，更新检查器将查找该分支中的readme.txt。否则，它将只查看master分支。

• 标签

  您可以跳过“稳定标签”部分，只创建一个名为v1.2.3或1.2.3的新Git标签。更新检查器将查看最近的标签，并选择看起来像最高版本号的标签。

  PUC不需要严格遵循SemVer。以下都是有效的标签名称：v1.2.3、v1.2-foo、1.2.3_rc1-ABC、1.2.3.4.5。但是，请注意，它不够智能，无法过滤alpha/beta/RC版本。

• 稳定分支

  将更新检查器指向一个稳定、生产就绪的分支。

   $updateChecker->setBranch('branch-name');

  PUC将定期检查主插件文件或style.css中的Version头部，如果它大于安装的版本，将显示通知。注意：如果将分支设置为master，更新检查器仍将首先查找标签。

GitLab集成

1. 下载最新版本并将plugin-update-checker目录复制到您的插件或主题。

2. 将以下代码添加到主插件文件或functions.php中，并定义您希望如何从Gitlab检查更新（请参阅：Gitlab：如何发布更新）

   require 'plugin-update-checker/plugin-update-checker.php';
   use YahnisElsts\PluginUpdateChecker\v5\PucFactory;
   
   $myUpdateChecker = PucFactory::buildUpdateChecker(
   	'https://gitlab.com/user-name/repo-name/',
   	__FILE__,
   	'unique-plugin-or-theme-slug'
   );
   
   //Optional: If you're using a private repository, specify the access token like this:
   $myUpdateChecker->setAuthentication('your-token-here');

   或者，如果您使用的是自托管的GitLab实例，则初始化更新检查器如下

   use YahnisElsts\PluginUpdateChecker\v5p2\Vcs\PluginUpdateChecker;
   use YahnisElsts\PluginUpdateChecker\v5p2\Vcs\GitLabApi;
   
   $myUpdateChecker = new PluginUpdateChecker(
   	new GitLabApi('https://myserver.com/user-name/repo-name/'),
   	__FILE__,
   	'unique-plugin-or-theme-slug'
   );
   //Optional: Add setAuthentication(...) and setBranch(...) as shown above.  

   如果您使用的是自托管的GitLab实例，并且有子组或嵌套组，则必须告诉更新检查器URL中的哪些部分是子组

   use YahnisElsts\PluginUpdateChecker\v5p2\Vcs\PluginUpdateChecker;
   use YahnisElsts\PluginUpdateChecker\v5p2\Vcs\GitLabApi;
   
   $myUpdateChecker = new PluginUpdateChecker(
   	new GitLabApi(
   		'https://myserver.com/group-name/subgroup-level1/subgroup-level2/subgroup-level3/repo-name/', 
   		null, 
   		'subgroup-level1/subgroup-level2/subgroup-level3'
   	),
   	__FILE__,
   	'unique-plugin-or-theme-slug'
   );

3. 仅插件：将按照 WordPress.org 插件 readme 标准 格式的 readme.txt 文件添加到您的存储库中。当用户点击“查看版本 1.2.3 详细信息”链接时，将显示此文件的 内容。

如何发布GitLab更新

可以通过3种不同方式检查GitLab仓库的更新。

• GitLab发行版

  使用GitLab上的“发行版”功能创建一个新发行版。标签名称应与版本号匹配。您可以在标签前添加一个v前缀，如v1.2.3。标记为“即将发布”的发行版将被自动忽略。

  如果您想使用自定义发行版资产，在创建更新检查器实例后调用enableReleaseAssets()方法

   $myUpdateChecker->getVcsApi()->enableReleaseAssets();

  默认情况下，PUC将使用第一个可用的资产链接，无论类型如何。您可以通过传递正则表达式到enableReleaseAssets()来让它选择第一个URL匹配正则表达式的链接。例如

   $myUpdateChecker->getVcsApi()->enableReleaseAssets('/\.zip($|[?&#])/i');

  提示：您可以使用Gitlab CI/CD流水线，通过通用包自动生成您的发布更新。有关通用包的更多信息，请参阅以下链接：- Gitlab CI/CD 发布文档 - Gitlab 发布资产作为通用包文档 - 使用发布通用包生成Sensei-LMS WordPress插件更新包的示例.gitlab-ci.yml文件

• 标签

  要发布版本1.2.3，创建一个名为v1.2.3或1.2.3的新Git标签。更新检查器将查看最近的标签，并使用看起来像最高版本号的标签。

  PUC不要求严格遵循SemVer。但是，请注意，它还不够智能，无法过滤alpha/beta/RC版本。如果这成为问题，您可能想使用GitLab分支。

• 稳定分支

  将更新检查器指向任何稳定、生产就绪的分支

   $myUpdateChecker->setBranch('stable-branch-name');

  PUC会定期检查主插件文件或style.css中的Version头信息，如果它大于已安装版本，则显示通知。注意：即使您将分支设置为main（默认）或master（历史默认），更新检查器仍会首先查找最近的发布和标签。

从4.x迁移

库的旧版本没有使用命名空间。为这些版本编写的代码需要更新才能与当前版本一起工作。至少，您需要更改工厂类的名称。

旧代码

$myUpdateChecker = Puc_v4_Factory::buildUpdateChecker(
	'https://example.com/info.json',
	__FILE__,
	'my-slug'
);

新代码

use YahnisElsts\PluginUpdateChecker\v5\PucFactory;

$myUpdateChecker = PucFactory::buildUpdateChecker(
	'https://example.com/info.json',
	__FILE__,
	'my-slug'
);

其他类也已被重命名，通常是通过简单地删除Puc_vXpY_前缀，并将Category_Thing转换为Category\Thing。以下是常用类及其新名称的表格

许可证管理

目前，更新检查器没有内置的许可证管理功能。它仅提供一些钩子，您可以使用它们，例如，将许可证密钥附加到更新请求（$updateChecker->addQueryArgFilter()）。如果您正在寻找管理和验证许可证的方法，请在此问题中发表反馈。

资源

• 这篇博客文章提供了更多有关更新检查器API的信息。略有过时。
• 调试栏 - 用于测试和调试更新检查器的有用工具。
• 更新格式参考 - 描述了更新检查器使用的基于JSON的更新信息格式支持的所有字段。仅涵盖插件。主题使用类似但更有限的格式。
• 保护下载链接 - 一般概述。
• 用于输入下载凭据的GUI
• 主题更新检查器 - 这是此更新检查器的较老、仅主题变体。