README

安装

建议您通过 Composer 将 Uplink 作为项目依赖项安装

composer require stellarwp/uplink

我们实际上推荐使用 Strauss 将此库包含到您的项目中。

幸运的是，将 Strauss 添加到您的 composer.json 仅仅比添加一个典型依赖项稍微复杂一些，所以请查看我们的 strauss 文档。

初始化库

初始化 StellarWP Uplink 库应在 plugins_loaded 动作中进行，最好是在优先级 0 时。

use StellarWP\Uplink\Uplink;

add_action( 'plugins_loaded', function() {
	/**
	 * Configure the container.
	 *
	 * The container must be compatible with stellarwp/container-contract.
	 * See here: https://github.com/stellarwp/container-contract#usage.
	 *
	 * If you do not have a container, we recommend https://github.com/lucatume/di52
	 * and the corresponding wrapper:
	 * https://github.com/stellarwp/container-contract/blob/main/examples/di52/Container.php
	 */
	$container = new Container();
	Config::set_container( $container );
	Config::set_hook_prefix( 'my-custom-prefix' );

	/*
	 * If you wish to allow a customer to authorize their product, set your Token Auth Prefix.
	 *
	 * This will allow storage of a unique token associated with the customer's license/domain.
	 *
	 * Important: The Token auth prefix should be the same across all of your products.
	 */
	Config::set_token_auth_prefix( 'my_origin' );

	// Optionally, change the default auth token caching.
	Config::set_auth_cache_expiration( WEEK_IN_SECONDS );

	// Or, disable it completely.
	Config::set_auth_cache_expiration( -1 );

	Uplink::init();
}, 0 );

翻译

该包使用 __( 'Invalid request: nonce field is expired. Please try again.', '%TEXTDOMAIN%' ) 函数进行翻译。为了将域名占位符 '%TEXTDOMAIN%' 更改为您的插件翻译域名，请运行

./bin/stellar-uplink domain=<your-plugin-domain>

或

./bin/stellar-uplink

并提示插件域名。您还可以将以下行添加到您的 composer 文件中，以自动运行命令

"scripts": {
	"stellar-uplink": [
	  "vendor/bin/stellar-uplink domain=<your-plugin-domain>"
	],
	"post-install-cmd": [
	  "@stellar-uplink"
	],
	"post-update-cmd": [
	  "@stellar-uplink"
	]
  }

在您的插件中嵌入许可证

StellarWP Uplink 插件包含嵌入式许可证密钥，因此用户在激活插件时不需要手动输入密钥。要使这成为可能，类必须位于特定位置，以便许可证服务器可以找到它。

# The class file should be in this path:
src/Uplink/Helper.php

文件应与以下内容匹配 - 保持 KEY 常量设置为空字符串，或者如果您想使用默认许可证密钥，请将其设置为该值。

<?php declare( strict_types=1 );

namespace Whatever\Namespace\Uplink;

final class Helper {
	public const KEY = '';
}

注册插件

注册插件以进行许可证和更新。

use StellarWP\Uplink\Register;

$plugin_slug    = 'my-plugin';
$plugin_name    = 'My Plugin';
$plugin_version = MyPlugin::VERSION;
$plugin_path    = 'my-plugin/my-plugin.php';
$plugin_class   = MyPlugin::class;
$license_class  = MyPlugin\Uplink\Helper::class;

Register::plugin(
	$plugin_slug,
	$plugin_name,
	$plugin_version,
	$plugin_path,
	$plugin_class,
	$license_class, // This is optional.
	false // Whether this is an oAuth plugin. Default false.
);

注册服务

注册服务以进行许可证。由于服务需要插件，我们从插件中提取版本和类信息。

use StellarWP\Uplink\Register;

$service_slug    = 'my-service';
$service_name    = 'My Service';
$service_version = MyPlugin::VERSION;
$plugin_path     = 'my-plugin/my-plugin.php';
$plugin_class    = MyPlugin::class;

Register::service(
	$service_slug,
	$service_name,
	$service_version,
	$plugin_path,
	$plugin_class,
	null,
	false
);

在您的设置页面渲染许可证密钥表单

为了渲染许可证密钥表单，只需将以下内容添加到您的设置页面、选项卡等。

⚠️ 这将在同一 Uplink/Container 实例中渲染所有已注册插件/服务的许可证密钥字段。

use StellarWP\Uplink as UplinkNamespace;

$form = UplinkNamespace\get_form();
$plugins = UplinkNamespace\get_plugins();

foreach ( $plugins as $plugin ) {
	$field = UplinkNamespace\get_field( $plugin->get_slug() );
	// Tha name property of the input field.
	$field->set_field_name( 'field-' . $slug );
	$form->add_field( $field );
}

$form->render();
// or echo $form->get_render_html();

要渲染单个产品的许可证密钥，请使用以下内容

use StellarWP\Uplink as UplinkNamespace;

$field = UplinkNamespace\get_field( 'my-test-plugin' );

$field->render();
// or echo $field->get_render_html();

示例：注册设置页面并渲染许可证字段

如果需要，为插件注册设置页面

add_action( 'admin_menu', function () {
    add_menu_page(
        'Sample',
        'Sample',
        'manage_options',
        'sample-plugin-lib',
        'render_settings_page',
        '',
        null
    );

}, 11 );

将以下行添加到您的设置页面。这将渲染带有标题和提交按钮的许可证密钥表单

use StellarWP\Uplink as UplinkNamespace;

function render_settings_page() {
    // ...
	$form = UplinkNamespace\get_form();
	$plugins = UplinkNamespace\get_plugins();

	foreach ( $plugins as $plugin ) {
		$field = UplinkNamespace\get_field( $plugin->get_slug() );
		// Tha name property of the input field.
		$field->set_field_name( 'field-' . $slug );
		$form->add_field( $field );
	}

	$form->show_button( true, __( 'Submit', 'text-domain' ) );

	$form->render();

    //....
}

许可证授权

⚠️ 您的 auth_url 已在 Stellar Licensing 服务器的“Origins”表中设置！在继续之前，您必须先请求添加此内容。

您可能希望在某些已知许可证已授权的情况下提供某些功能。

此库提供了与 Uplink Origin 插件一起工作以获取和存储唯一令牌的工具。

在顶部根据说明定义 Config::set_token_auth_prefix() 后，此功能将启用以下功能

1. 当用户在 wp-admin 中时，在插件中的任何位置渲染“连接”按钮的能力，使用以下提供的函数。
2. 一旦他们被授权，按钮将显示“断开连接”，这将删除本地存储的令牌。
3. 客户网站在 wp-admin 中接受特定的查询变量，这些变量将存储生成的令牌，以及可选的新产品 Slugged 许可证密钥。
4. 检查许可证是否已授权，无论是通过许可证验证有效载荷还是手动检查。

⚠️ 生成令牌需要在您的源网站上手动配置 Uplink Origin 插件。

渲染授权按钮

💡 注意：按钮仅在满足以下条件时渲染

1. 您在 StellarWP 许可证服务器上设置了 auth_url。
2. 当前用户是超级管理员（可以使用 WP 过滤器更改）。
3. 这不是一个多站点安装，或者...
4. 如果使用子文件夹的多站点，则仅在根网络仪表板中。
5. 如果使用非子文件夹的多站点，并且在子站上，并且网络级别上尚未存在令牌，则需要在网络级别上管理。

// Call the namespaced function with your plugin slug.
\StellarWP\Uplink\render_authorize_button( 'kadence-blocks-pro' );

您还可以传入自定义许可证域名，该域名可以从 Uplink Origin 端的 uplink_domain 查询变量中获取

// Call the namespaced function with your plugin slug and license domain.
\StellarWP\Uplink\render_authorize_button( 'kadence-blocks-pro', 'customer-site.com' );

💡 该按钮可以通过过滤器进行高度自定义，请参阅 Authorize_Button_Controller.php。

手动检查许可证是否远程授权

这会将连接到许可证服务器以实时检查许可证是否已授权。请谨慎使用。

$token       = \StellarWP\Uplink\get_authorization_token( 'my-plugin-slug' );
$license_key = \StellarWP\Uplink\get_license_key( 'my-plugin-slug' );
$domain      = \StellarWP\Uplink\get_license_domain();

if ( ! $token || ! $license_key || ! $domain ) {
	return; // or, log/show errors.
}

$is_authorized = \StellarWP\Uplink\is_authorized( $license_key, 'my-plugin-slug', $token, $domain );

echo $is_authorized ? esc_html__( 'authorized' ) : esc_html__( 'not authorized' );

手动获取授权 URL

如果由于某些原因需要手动获取您的 auth_url，您可以通过以下方式完成

echo esc_url( \StellarWP\Uplink\get_auth_url( 'my-plugin-slug' ) );

💡 使用瞬态，Auth URL 连接被缓存一天。

回调重定向

Origin 生成的回调重定向看起来类似于以下内容，其中 uplinksample.lndo.site 是您的客户网站

https://uplinksample.lndo.site/wp-admin/import.php?uplink_token=d9a407d0-0eb1-41cf-8cd0-e5da668143b4&_uplink_nonce=Oyj13TCvhaa12IJm

Origin 负责请求 StellarWP 许可证生成令牌并将重定向回客户最初点击按钮的位置。

以下查询变量可用于参考

💡 注意：此数据在检测到时自动存储，使用 admin_init 钩子！

1. uplink_token - 由 StellarWP 许可证生成的唯一 UUIDv4 令牌。
2. _uplink_nonce - 与回调 URL 一起发送的原始 nonce，作为“连接”按钮的一部分。
3. uplink_license（可选）- 是否应更新或设置许可证密钥。
4. uplink_slug（可选）- 我们正在更新许可证的产品或服务 Slugged。

⚠️ 如果 uplink_license 存在，则必须提供 uplink_slug！