如何为WordPress插件开发预装设置数据

为WordPress插件安装设置数据

在开发 WordPress 插件时,一个关键步骤是预装重要数据,确保插件从一开始就能顺利运行。以活动管理器插件为例。安装时,如果插件能自动生成一个名为 “Upcoming Events” 的页面,显示未来活动的列表,这将大有裨益。

这个预先配置好的页面嵌入了类似 [event_list number="10" scope="future" status="publish"] 这样的简码,让用户无需阅读文档就能立即利用插件的功能。

安装数据不仅在首次安装插件时有帮助,在随后更新插件时也有帮助。例如,如果更新引入了日历视图功能,插件可以自动创建一个新页面 “Events Calendar“,通过 [event_calendar status="publish"] 这样的简码来展示这一新增功能。

一般来说,数据安装的范围涵盖各种需求:

  • 生成具有特定标题和内容的新页面。
  • 为插件创建的自定义帖子类型(CPT)添加条目。
  • wp_options 表中插入默认设置
  • 为用户角色分配新功能
  • 为插件提供的新功能或更新功能向用户分配元数据(例如,用户可更改事件日期格式,并首先为所有用户添加默认值)
  • 创建插件上下文中常用的类别,如 “conferences” 或 “sports”。

安装数据必须是一个渐进的过程,否则我们可能会创建重复的条目。

例如,如果插件 1.1 版引入了 “Upcoming Events” 页面,而用户从 1.0 版进行了更新,则只应安装与 1.1 版相关的新数据。这种增量式更新可确保在 1.2 版推出日历功能时,只添加新的 “Events Calendar” 页面,避免与 “Upcoming Events” 页面重复。

因此,在更新时,插件必须检索之前安装的版本,并只安装与新版本相对应的数据。

本文将解释如何在 WordPress 插件中安装初始数据,并在进一步更新时不断添加新数据。

提供当前版本

为了处理增量过程,插件必须跟踪其当前版本,通常在插件主文件的头文件中声明。当然,我们不能直接引用它,因为它在 PHP 注释中。因此,我们还需要在变量中定义该值,并将其提供给负责初始化和配置的 Plugin 类:

<?php
/*
Plugin Name: My plugin
Version: 1.6
*/
// Same version as in the header
$pluginVersion = '1.6';
new Plugin($pluginVersion)->setup();

Plugin 类利用 PHP 8.0 的构造函数属性推广功能,存储了这个版本,以便我们以后引用:

<?php
class Plugin {
public function __construct(
protected string $pluginVersion,
) {}
public function setup(): void
{
// Initialization logic here...
}
// ...
}

请注意,初始化和配置插件的逻辑被添加到了 setup 方法中,而不是构造函数中。这是因为构造函数必须避免产生副作用;否则,我们在扩展或组合 Plugin 类时可能会产生错误。

让我们来看看这种情况是如何发生的。假设我们最终添加了一个 BetterPlugin 类,该类由 Plugin 类的功能组成:

class BetterPlugin {
public function printSomething(): string
{
$pluginVersion = '1.0';
$plugin = new Plugin($pluginVersion);
return '<div class="wrapper">' . $plugin->printSomething() . '</div>';
}
}

每当在 printSomething 内执行 new Plugin() 时,都会创建一个新的 Plugin 实例。如果将配置逻辑添加到构造函数中,那么每次创建新的 Plugin 对象时都会执行配置逻辑。在我们的例子中,我们只想创建一次 “Upcoming Events” 页面,而不是多次。通过在设置方法中添加逻辑,我们可以避免这个问题。

跟踪以前的版本

WordPress 没有提供方便的方法来检索被替换插件的版本。因此,我们必须自己在数据库的 wp_options 表中存储这个值。

将版本存储在 ” myplugin_version ” 条目下,其中 myplugin_ 是插件的名称(例如 eventsmanager_version )。重要的是,在所有设置前都要加上 myplugin_ ,以避免潜在冲突,因为我们无法确保其他插件不会添加 version 选项。

在每次请求中加载插件时, Plugin 已经知道当前的版本(来自前面的属性 $pluginVersion ),并将从数据库中检索上次存储的版本。这种比较决定了插件的状态:

  • 新安装:检测数据库中是否缺少插件的版本条目,表示首次安装(即 $storedPluginVersionnull
  • 更新:当当前版本超过数据库存储的版本时识别,表明需要升级。
  • 否则,没有变化

无论何时发生变化,我们都会调用 prepareAndInstallPluginSetupData 来安装相应的数据,无论是新安装(这种情况下必须安装所有版本的所有数据)还是更新(只安装所有新版本的数据)。可为空的 $previousVersion 变量会指示是哪种情况( $previousVersionnull  => 新安装)。

调用此方法后,我们还必须在数据库中存储当前插件版本,使其成为新的 “最后存储” 版本。这项工作必须在调用 prepareAndInstallPluginSetupData 之后完成,这样,如果该方法出错(如抛出 RuntimeException )且数据未安装,数据库中仍会存储上一版本,并在下一次请求时尝试新一轮安装数据。

<?php
class Plugin {
// ...
public function setup(): void
{
if (!is_admin()) {
return;
}
$this->managePluginDataVersioning();
}
/**
* If the plugin has just been newly-installed + activated
* or updated, install the appropriate data.
*/
protected function managePluginDataVersioning(): void
{
$myPluginVersionOptionName = 'myplugin_version';
$storedPluginVersion = get_option($myPluginVersionOptionName, null);
// Check if the main plugin has been activated or updated
$isPluginJustFirstTimeActivated = $storedPluginVersion === null;
$isPluginJustUpdated = !$isPluginJustFirstTimeActivated && $storedPluginVersion !== $this->pluginVersion;
// If there were no changes, nothing to do
if (!$isPluginJustFirstTimeActivated && !$isPluginJustUpdated) {
return;
}
\add_action(
'init',
function () use ($myPluginVersionOptionName, $storedPluginVersion): void {
$this->prepareAndInstallPluginSetupData($storedPluginVersion);
// Update on the DB
update_option($myPluginVersionOptionName, $this->pluginVersion);
}
);
}
protected function prepareAndInstallPluginSetupData(?string $previousVersion): void
{
// Installation logic...
}
}

请注意, prepareAndInstallPluginSetupData(以及随后的数据库更新)是在 init 操作钩子上执行的。这是为了确保内容管理系统中的所有数据都已准备好供检索和操作。

特别是,init 钩子之前,不能访问分类标准(标签和类别)。如果插件的安装过程需要创建 CPT 条目并为其分配自定义类别,则该过程只能从 init 钩子开始运行。

性能角度看,每次请求都从数据库访问上次存储的版本并不理想。为了改善这种情况,可以将插件所需的所有选项合并到一个数组中,将它们存储在一个条目中,然后通过对数据库的一次调用访问所有选项。

例如,如果插件还需要存储一个 myplugin_date_format 选项来显示事件日期,我们可以创建一个具有 version 和 date_format 属性的单一条目 myplugin_options

要访问上次存储的版本,PHP 代码必须进行如下调整:

<?php
class Plugin {
// ...
protected function managePluginDataVersioning(): void
{
$myPluginOptionsOptionName = 'myplugin_options';
$myPluginOptions = get_option($myPluginOptionsOptionName, []);
$storedPluginVersion = $myPluginOptions['version'] ?? null;
// ...
\add_action(
'init',
function () use ($myPluginOptionsOptionName, $myPluginOptions): void {
// ...
// Update on the DB
$myPluginOptions['version'] = $this->pluginVersion;
update_option($myPluginOptionsOptionName, $myPluginOptions);
}
);
}
}

避免同时请求安装重复数据

如果两个或两个以上的用户在同一时间访问 wp-admin,安装过程可能会被触发一次以上。为避免同一数据被安装两次或更多次,我们使用暂态作为标记,只允许第一个请求安装数据:

  • 检查暂存器 myplugin_installing_plugin_setup_data 是否存在(再次强调,该名称必须以 myplugin_ 作为前缀);如果存在,则什么也不做(因为其他进程正在安装数据)。
  • 否则,在数据库中存储瞬时数据,以安装数据所需的合理最长时间(例如 30 秒)
  • 安装数据
  • 删除暂存数据

代码如下:

<?php
class Plugin {
// ...
/**
* Use a transient to make sure that only one instance
* will install the data. Otherwise, two requests
* happening simultaneously might execute the logic
*/
protected function prepareAndInstallPluginSetupData(?string $previousVersion): void
{
$transientName = 'myplugin_installing_plugin_setup_data';
$transient = \get_transient($transientName);
if ($transient !== false) {
// Another instance is executing this code right now
return;
}
\set_transient($transientName, true, 30);
$this->installPluginSetupData($previousVersion);
\delete_transient($transientName);
}
protected function installPluginSetupData(?string $previousVersion): void
{
// Do something...
}
}

安装所有版本的数据

如前所述,如果更新插件,我们必须只安装新版本的数据,而不是所有版本的数据。这意味着我们需要按版本管理要安装的数据。

在下面的代码中,数组 $versionCallbacks 表示每个版本要执行的函数,该函数执行安装数据的逻辑。我们遍历所有版本的列表,使用 version_compare 将每个版本与上一个版本进行比较,如果比较结果大于上一个版本,则执行相应的函数安装相应的数据。

请注意,如果 $previousVersionnull (即新安装的版本),则会执行所有函数。

class Plugin {
/**
* Provide the installation in stages, version by version, to
* be able to execute it both when installing/activating the plugin,
* or updating it to a new version with setup data.
*
* The plugin's setup data will be installed if:
*
* - $previousVersion = null => Activating the plugin for first time
* - $previousVersion < someVersion => Updating to a new version that has data to install
*/
protected function installPluginSetupData(?string $previousVersion): void
{
$versionCallbacks = [
'1.1' => $this->installPluginSetupDataForVersion1Dot1(...),
'1.2' => $this->installPluginSetupDataForVersion1Dot2(...),
// ... Add more versions
];
foreach ($versionCallbacks as $version => $callback) {
/**
* If the previous version is provided, check if the corresponding update
* has already been performed, then skip
*/
if ($previousVersion !== null && version_compare($previousVersion, $version, '>=')) {
continue;
}
$callback();
}
}
protected function installPluginSetupDataForVersion1Dot1(): void
{
// Do something...
}
protected function installPluginSetupDataForVersion1Dot2(): void
{
// Do something...
}
}

为每个特定版本安装数据

最后,我们必须为每个版本安装实际数据(创建页面、CPT 条目、添加选项等)。

在这段代码中,我们为事件管理器插件添加了适用于 v1.1 版本的 “Upcoming Events” 页面:

class Plugin {
// ...
protected function installPluginSetupDataForVersion1Dot1(): void
{
\wp_insert_post([
'post_status' => 'publish',
'post_type' => 'page',
'post_title' => \__('Upcoming Events', 'myplugin'),
'post_content' => '[event_list number="10" scope="future"]',
]);
}
// ...
}

然后,我们为 v1.2 版创建 “Events Calendar” 页面(在本例中,使用页面上的 Gutenberg 区块,添加名为 event-calendar 的自定义块):

class Plugin {
// ...
protected function installPluginSetupDataForVersion1Dot2(): void
{
\wp_insert_post([
'post_status' => 'publish',
'post_type' => 'page',
'post_title' => \__('Events Calendar', 'myplugin'),
'post_content' => serialize_blocks([
[
'blockName' => 'myplugin/event-calendar',
'attrs' => [
'status' => 'publish',
],
'innerContent' => [],
],
]),
]);
}
}

将所有代码整合在一起

我们完成了!Plugin  类的全部 PHP 代码如下,其中包含跟踪插件版本和安装相应数据的逻辑:

<?php
class Plugin {
public function __construct(
protected string $pluginVersion,
) {
}
public function setup(): void
{
if (!is_admin()) {
return;
}
$this->managePluginDataVersioning();
}
/**
* If the plugin has just been newly-installed + activated
* or updated, install the appropriate data.
*/
protected function managePluginDataVersioning(): void
{
$myPluginVersionOptionName = 'myplugin_version';
$storedPluginVersion = get_option($myPluginVersionOptionName, null);
// Check if the main plugin has been activated or updated
$isPluginJustFirstTimeActivated = $storedPluginVersion === null;
$isPluginJustUpdated = !$isPluginJustFirstTimeActivated && $storedPluginVersion !== $this->pluginVersion;
// If there were no changes, nothing to do
if (!$isPluginJustFirstTimeActivated && !$isPluginJustUpdated) {
return;
}
\add_action(
'init',
function () use ($myPluginVersionOptionName, $storedPluginVersion): void {
$this->prepareAndInstallPluginSetupData($storedPluginVersion);
// Update on the DB
update_option($myPluginVersionOptionName, $this->pluginVersion);
}
);
}
/**
* Use a transient to make sure that only one instance
* will install the data. Otherwise, two requests
* happening simultaneously might both execute
* this logic
*/
protected function prepareAndInstallPluginSetupData(?string $previousVersion): void
{
$transientName = 'myplugin_installing_plugin_setup_data';
$transient = \get_transient($transientName);
if ($transient !== false) {
// Another instance is executing this code right now
return;
}
\set_transient($transientName, true, 30);
$this->installPluginSetupData($previousVersion);
\delete_transient($transientName);
}
/**
* Provide the installation in stages, version by version, to
* be able to execute it both when installing/activating the plugin,
* or updating it to a new version with setup data.
*
* The plugin's setup data will be installed if:
*
* - $previousVersion = null => Activating the plugin for first time
* - $previousVersion < someVersion => Updating to a new version that has data to install
*/
protected function installPluginSetupData(?string $previousVersion): void
{
$versionCallbacks = [
'1.1' => $this->installPluginSetupDataForVersion1Dot1(...),
'1.2' => $this->installPluginSetupDataForVersion1Dot2(...),
// ... Add more versions
];
foreach ($versionCallbacks as $version => $callback) {
/**
* If the previous version is provided, check if the corresponding update
* has already been performed, then skip
*/
if ($previousVersion !== null && version_compare($previousVersion, $version, '>=')) {
continue;
}
$callback();
}
}
protected function installPluginSetupDataForVersion1Dot1(): void
{
\wp_insert_post([
'post_status' => 'publish',
'post_type' => 'page',
'post_title' => \__('Upcoming Events', 'myplugin'),
'post_content' => '[event_list number="10" scope="future" status="publish"]',
]);
}
protected function installPluginSetupDataForVersion1Dot2(): void
{
\wp_insert_post([
'post_status' => 'publish',
'post_type' => 'page',
'post_title' => \__('Events Calendar', 'myplugin'),
'post_content' => serialize_blocks([
[
'blockName' => 'myplugin/event-calendar',
'attrs' => [
'status' => 'publish',
],
'innerContent' => [],
],
]),
]);
}
}

小结

WordPress 插件在安装时通常需要安装数据。此外,当新版本的插件提供新功能时,插件也可能需要在更新时安装数据。

在本文中,我们学习了如何跟踪版本并为插件安装相应的数据。

您的 WordPress 插件可以从安装数据中受益吗?请在评论中告诉我们。

评论留言