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（您的slug）”面板。
4. 点击“立即检查”按钮。

注意

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

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

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

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详细信息”链接时，它将显示。

  如果您想使用发布资产，请在创建更新检查器实例后调用 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\v5p4\Vcs\PluginUpdateChecker;
   use YahnisElsts\PluginUpdateChecker\v5p4\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\v5p4\Vcs\PluginUpdateChecker;
   use YahnisElsts\PluginUpdateChecker\v5p4\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，创建一个新的Git标签，命名为v1.2.3或1.2.3。更新检查器将查看最近的标签，并使用看起来像最高版本号的标签。

  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
• 主题更新检查器 - 这是此更新检查器的较旧、仅主题变体。