yahnis-elsts / wp-update-server
WordPress 插件和主题的自定义更新 API 服务器。
Requires
- php: >=5.3.0
Suggests
- ext-mbstring: Used for escaping log values in a utf8 compatible manner. If the extension isn't installed logged values are handled as single-byte character strings.
README
WordPress 插件和主题的自定义更新 API。
功能
-
提供插件和主题的更新。
从用户的角度来看,更新就像官方 WordPress.org 目录中列出的插件和主题一样工作。
-
易于设置。
只需将脚本目录上传到您的服务器,并将插件或主题 ZIP 文件放入
packages
子目录。现在您已经在http://yourserver.com/wp-update-server/?action=get_metadata&slug=your-plugin
有了一个工作的更新 API。 -
易于集成到现有的插件和主题中。
只需要大约 5 行代码。有关详细信息,请参阅 插件更新检查器 和 主题更新检查器 文档,或者直接滚动到“入门”部分查看简短版本。
-
最小的服务器要求。
服务器组件需要 PHP 5.3+ 和 Zip 扩展。客户端库只需要 PHP 5.2 - 与当前版本的 WordPress 相同。
-
设计用于可扩展性。
想要保护您的升级下载链接?或者使用自定义日志记录器或缓存?也许您的插件没有标准的
readme.txt
,您更喜欢从数据库中加载更改日志和其他更新元数据?通过扩展Wpup_UpdateServer
类创建自己的定制服务器。请参阅下面的示例。
入门
设置服务器
此设置过程的部分对插件和主题都相同。为了简洁起见,我将从插件的角度描述它。
- 将
wp-update-server
目录上传到您的网站。如果您想,可以将其重命名为其他名称(例如updates
)。 - 使
cache
和logs
子目录可由 PHP 写入。 - 创建插件目录的 Zip 存档。存档的名称必须与目录名称相同,并加上 ".zip"。)
- 将 Zip 文件复制到
packages
子目录。 - 通过在浏览器中访问
/wp-update-server/?action=get_metadata&slug=plugin-directory-name
验证 API 是否工作。您应该看到一个包含有关您插件的各种信息的 JSON 文档(名称、版本、描述等)。
提示:使用 JSONView 扩展(Firefox、Chrome)在浏览器中美化打印 JSON。
在创建 Zip 文件时,请确保插件文件位于目录内,而不是存档根目录中。例如,假设您有一个名为 "My Cool Plugin" 的插件,它位于 /wp-content/plugins/my-cool-plugin
中。ZIP 文件应命名为 my-cool-plugin.zip
,并包含以下内容
/my-cool-plugin
/css
/js
/another-directory
my-cool-plugin.php
readme.txt
...
如果您将所有内容都放在根目录中,更新通知可能显示得很好,但您在尝试安装更新时可能会遇到无法解释的问题,因为 WordPress 预期插件文件位于子目录中。
与插件集成
现在服务器已经准备就绪,下一步是让您的插件查询它以获取更新。我们将使用 plugin-update-checker 库来实现这一点。
-
下载更新检查器。
-
将
plugin-update-checker
目录移动到您的插件目录中。 -
将以下代码添加到您的主插件文件中
require 'path/to/plugin-update-checker/plugin-update-checker.php'; use YahnisElsts\PluginUpdateChecker\v5\PucFactory; $MyUpdateChecker = PucFactory::buildUpdateChecker( 'http://example.com/wp-update-server/?action=get_metadata&slug=plugin-directory-name', //Metadata URL. __FILE__, //Full path to the main plugin file. 'plugin-directory-name' //Plugin slug. Usually it's the same as the name of the directory. );
-
当您准备好发布更新时,只需按照上述方法将插件目录压缩,并将其放在服务器上的
packages
子目录中(覆盖之前的版本)。
默认情况下,库会每天检查两次更新。如果更新检查器发现新版本可用,它将在WordPress仪表板中显示更新通知,用户可以通过点击“立即升级”链接来安装它。从用户的角度来看,这与托管在WordPress.org上的插件一样。
有关详细使用说明和更多示例,请参阅更新检查器文档。
提示:为您的插件创建一个readme.txt
文件。如果您已经有了,更新服务器将使用它来生成用户在点击更新通知中的“查看版本x.y.z详细信息”链接时看到的插件信息页面。readme必须符合WordPress.org readme标准。
注意:您的插件或主题必须处于激活状态才能更新工作。一个后果是,在多站点安装中,只有当您的插件在主站点上激活时,更新才会显示。这是因为只有主站点上启用的插件才会加载到网络管理器中。为了参考,主站点是所有站点列表中路径为"/"的站点。
与主题集成
-
下载主题更新检查器库。
-
将
theme-updates
目录放置在您的includes
或等效位置。 -
将此片段添加到您的
functions.php
require 'path/to/theme-updates/theme-update-checker.php'; $MyThemeUpdateChecker = new ThemeUpdateChecker( 'theme-directory-name', //Theme slug. Usually the same as the name of its directory. 'http://example.com/wp-update-server/?action=get_metadata&slug=theme-directory-name' //Metadata URL. );
-
在您的
style.css
中添加一个Details URI
标题Details URI: http://example.com/my-theme-changelog.html
此标题指定了用户在点击更新通知中的“查看版本x.y.z详细信息”链接时将看到的页面。将其设置为“版本z.y.z的新功能”页面或主题主页的URL。
与插件更新一样,主题更新检查器会每12小时查询服务器以获取主题详细信息,并在有新版本可用时在WordPress仪表板中显示更新通知。
有关更多信息,请参阅主题更新检查器文档。
更新:现在plugin-update-checker库也支持主题更新。旧的主题更新检查器不再积极维护。
高级主题
日志记录
服务器将所有API请求记录到/logs/request.log
文件中。每行代表一个请求,格式如下
[timestamp] IP_address action slug installed_version wordpress_version site_url query_string
缺失或不适用字段以破折号“-”代替。记录器从WordPress添加到通过其HTTP API发送的所有请求的“User-Agent”标题中提取WordPress版本和站点URL。如果您通过浏览器进行API请求或标题被插件移除或覆盖(一些安全插件会这样做),则这些字段将不存在。
扩展服务器
要自定义更新服务器的工作方式,创建自己的服务器类,该类扩展Wpup_UpdateServer,并编辑初始化脚本(如果您作为独立应用程序运行服务器,则为index.php
),以便加载和使用新类。
例如,让我们进行一个简单的修改,禁用下载并从更新API返回的插件详细信息中删除下载URL。这可以作为需要授权才能下载更新的自定义服务器的基础。
将新文件MyCustomServer.php
添加到wp-update-server
class MyCustomServer extends Wpup_UpdateServer { protected function filterMetadata($meta, $request) { $meta = parent::filterMetadata($meta, $request); unset($meta['download_url']); return $meta; } protected function actionDownload(Wpup_Request $request) { $this->exitWithError('Downloads are disabled.', 403); } }
编辑index.php
以使用新类
require __DIR__ . '/loader.php'; require __DIR__ . '/MyCustomServer.php'; $server = new MyCustomServer(); $server->handleRequest();
从其他脚本运行服务器
虽然使用更新服务器最简单的方式是将其作为独立应用程序运行,但这并非唯一的方式。如果您需要的话,也可以将其加载为第三方库,并创建自己的服务器实例。这样可以让您在将查询参数传递给服务器之前对其进行过滤和修改,从WordPress插件中运行它,使用您自己的服务器类,等等。
要从您自己的应用程序运行服务器,您需要做三件事
- 包含
/wp-update-server/loader.php
。 - 创建
Wpup_UpdateServer
或其扩展类的实例。 - 调用
handleRequest($queryParams)
方法。
以下是一个基本示例插件,它从WordPress内部运行更新服务器
<?php /* Plugin Name: Plugin Update Server Description: An example plugin that runs the update API. Version: 1.0 Author: Yahnis Elsts Author URI: http://w-shadow.com/ */ require_once __DIR__ . '/path/to/wp-update-server/loader.php'; class ExamplePlugin { protected $updateServer; public function __construct() { $this->updateServer = new MyCustomServer(home_url('/')); //The "action" and "slug" query parameters are often used by the WordPress core //or other plugins, so lets use different parameter names to avoid conflict. add_filter('query_vars', array($this, 'addQueryVariables')); add_action('template_redirect', array($this, 'handleUpdateApiRequest')); } public function addQueryVariables($queryVariables) { $queryVariables = array_merge($queryVariables, array( 'update_action', 'update_slug', )); return $queryVariables; } public function handleUpdateApiRequest() { if ( get_query_var('update_action') ) { $this->updateServer->handleRequest(array_merge($_GET, array( 'action' => get_query_var('update_action'), 'slug' => get_query_var('update_slug'), ))); } } } class MyCustomServer extends Wpup_UpdateServer { protected function generateDownloadUrl(Wpup_Package $package) { $query = array( 'update_action' => 'download', 'update_slug' => $package->slug, ); return self::addQueryArg($query, $this->serverUrl); } } $examplePlugin = new ExamplePlugin();
注意:如果您打算在实践中使用类似上述内容,您可能需要重写 Wpup_UpdateServer::generateDownloadUrl()
来自定义URL或更改查询参数。
保护下载链接
有关高级概述和一些简要示例,请参阅这篇博客文章。
分析
您可以使用wp-update-server-stats工具解析服务器日志并显示统计信息,例如活跃安装数量、活跃版本等。