yahnis-elsts/wp-update-server

WordPress 插件和主题的自定义更新 API 服务器。

v2.0.1 2022-12-16 18:43 UTC

This package is auto-updated.

Last update: 2024-08-30 01:07:05 UTC


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 类创建自己的定制服务器。请参阅下面的示例。

入门

设置服务器

此设置过程的部分对插件和主题都相同。为了简洁起见,我将从插件的角度描述它。

  1. wp-update-server 目录上传到您的网站。如果您想,可以将其重命名为其他名称(例如 updates)。
  2. 使 cachelogs 子目录可由 PHP 写入。
  3. 创建插件目录的 Zip 存档。存档的名称必须与目录名称相同,并加上 ".zip"。)
  4. 将 Zip 文件复制到 packages 子目录。
  5. 通过在浏览器中访问 /wp-update-server/?action=get_metadata&slug=plugin-directory-name 验证 API 是否工作。您应该看到一个包含有关您插件的各种信息的 JSON 文档(名称、版本、描述等)。

提示:使用 JSONView 扩展(FirefoxChrome)在浏览器中美化打印 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 库来实现这一点。

  1. 下载更新检查器。

  2. plugin-update-checker目录移动到您的插件目录中。

  3. 将以下代码添加到您的主插件文件中

    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.
    );
  4. 当您准备好发布更新时,只需按照上述方法将插件目录压缩,并将其放在服务器上的packages子目录中(覆盖之前的版本)。

默认情况下,库会每天检查两次更新。如果更新检查器发现新版本可用,它将在WordPress仪表板中显示更新通知,用户可以通过点击“立即升级”链接来安装它。从用户的角度来看,这与托管在WordPress.org上的插件一样。

有关详细使用说明和更多示例,请参阅更新检查器文档

提示:为您的插件创建一个readme.txt文件。如果您已经有了,更新服务器将使用它来生成用户在点击更新通知中的“查看版本x.y.z详细信息”链接时看到的插件信息页面。readme必须符合WordPress.org readme标准

注意:您的插件或主题必须处于激活状态才能更新工作。一个后果是,在多站点安装中,只有当您的插件在主站点上激活时,更新才会显示。这是因为只有主站点上启用的插件才会加载到网络管理器中。为了参考,主站点是所有站点列表中路径为"/"的站点。

与主题集成

  1. 下载主题更新检查器库。

  2. theme-updates目录放置在您的includes或等效位置。

  3. 将此片段添加到您的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.
    );
  4. 在您的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插件中运行它,使用您自己的服务器类,等等。

要从您自己的应用程序运行服务器,您需要做三件事

  1. 包含 /wp-update-server/loader.php
  2. 创建 Wpup_UpdateServer 或其扩展类的实例。
  3. 调用 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工具解析服务器日志并显示统计信息,例如活跃安装数量、活跃版本等。