README

WordPress 管理通知的简化 OOP 实现。

• 目标，或者这个包能做什么？
• 安装
• 用法
  • 示例
  • 通知
    • __construct(string $handle, string $content, string $type = null)
  • StickyNotice
    • __construct(string $handle, string $content, string $type = null)
  • 存储
    • __construct(string $optionKey)
    • add(NoticeInterface ...$notices)
    • delete(string $handle)
  • Notifier
    • __construct(string $action, StoreInterface $store)
  • 工厂
    • build(string $optionKey, string $action): Store
• 常见问题解答
  • 我能实现自己的通知类吗？
  • 我能使用除 wp_option 表之外的其他存储方案吗？
  • 这是一个插件吗？
  • 当 wp.org 插件团队告诉我清理 vendor 文件夹时，我该怎么做？
  • 两个不同的插件可以同时使用这个包吗？
  • 你有使用这个包的演示插件吗？
  • 你有使用这个包的真实生活示例吗？
  • 这看起来很棒。我在哪里可以找到更多类似的好东西？
• 支持
  • 为什么不雇用我？
  • 想以其他方式帮忙吗？想成为赞助商吗？
• 开发
• 运行测试
• 反馈
• 变更日志
• 安全
• 贡献
• 致谢
• 许可证

目标，或者这个包能做什么？

安装

应通过 composer 安装，有关如何安装 composer 的详细信息，请参阅 https://getcomposer.org.cn/。

$ composer require typisttech/wp-admin-notices

您应将所有 WP Admin Notices 类放在您自己的命名空间下，以避免类名冲突。

• imposter-plugin
• mozart

用法

示例

use TypistTech\WPAdminNotices\Factory;
use TypistTech\WPAdminNotices\Notice;
use TypistTech\WPAdminNotices\StickyNotice;

$store = Factory::build('my_unique_demo_option', 'my_unique_demo_action');

add_action('admin_init', function () use ($store) {
        $notice = new Notice('example-notice-1', 'my notice message');
        $store->add($notice);
    }
);

add_action('post_updated', function ($post_id) use ($store) {
        $notices[] = new Notice(
            'example-notice-2',
            "<p><strong>WPAdminNotices</strong>: Post ID: $post_id has been updated.</p>",
            Notice::SUCCESS
        );
        $notices[] = new StickyNotice(
            'example-notice-3',
            '<p><strong>WPAdminNotices</strong>: StickyNotice persists in database until user clicks to dismiss it.</p>'
        );
        $store->add(...$notices);
    }
);

通知

一次性通知，保证只显示一次。

__construct(string $handle, string $content, string $type = null)

Notice 构造函数。

• @param string $handle 通知的唯一标识符。
• @param string $content 通知的 HTML 内容。
• @param string|null $type 通知的类型。期望为 Notice::UPDATE_NAG、Notice::ERROR、Notice::WARNING、Notice::INFO 或 Notice::SUCCESS 之一。默认为 Notice::INFO。

Notice::UPDATE_NAG 不适用于常规管理通知。请参阅 WordPress codex。

$notice = new Notice('example-notice', '<strong>Hello</strong> World!', Notice::SUCCESS);

StickyNotice

StickyNotice 会在用户点击关闭之前在数据库中持续存在。

__construct(string $handle, string $content, string $type = null)

StickyNotice 构造函数。

• @param string $handle 通知的唯一标识符。也用于永久关闭一个粘性通知。
• @param string $content 通知的 HTML 内容。
• @param string|null $type 通知的类型。期望为 StickyNotice::ERROR、StickyNotice::WARNING、StickyNotice::INFO 或 StickyNotice::SUCCESS 之一。默认为 StickyNotice::INFO。

UPDATE_NAG 不适用于 StickyNotice。

$stickyNotice = new StickyNotice('example-sticky-notice', 'I wont go away until users click on me.', StickyNotice::WARNING);

存储

默认情况下，WP Admin Notices 通过 Store 将通知存储在 WordPress 的 wp_option 表中。如果您想使用其他存储方案，请参阅 常见问题解答。

__construct(string $optionKey)

Store 构造函数。

• @param string $optionKey 选项表中保存所有队列通知的键。

$store = new Store('my_unique_option_key');

add(NoticeInterface ...$notices)

将管理通知入队到数据库。

不仅限于 Notice 和 StickyNotice，接受任何 NoticeInterface 实例。见 常见问题解答。

• @param NoticeInterface[] ...$notices 要入队的通知。

$store->add($notice1, $notice2);

// To update a notice, re-add with the same handle.
$oldNotice = new Notice('i-am-unique', "Chaos isn't a pit.");
$store->add($oldNotice);

$newNotice = new Notice('i-am-unique', 'Chaos is a ladder.');
$store->add($newNotice);

delete(string $handle)

删除入队通知。

• @param string $handle 要删除的通知的处理程序。

$store->delete('i-am-unique');

Notifier

Notifier 通过操作钩子处理 WordPress 与此包之间的所有交互。除非您使用 Factory，否则您必须通过 add_action 将其连接到 WordPress。

__construct(string $action, StoreInterface $store)

Notifier 构造函数。

• @param string $action 粘性通知的 AJAX 请求 'action' 属性。
• @param StoreInterface $store 通知存储的连接器。

$store = new Store('my_unique_option_key');
$notifier = new Notifier('my_unique_action', $store);

add_action('admin_notices', [$notifier, 'renderNotices']);
add_action("wp_ajax_my_unique_action", [$notifier, 'dismissNotice']);
add_action('admin_footer', [$notifier, 'renderScript']);

工厂

Factory 是一个辅助类，用于减少使用默认 Store 类的开发者的样板代码。如果您使用 自定义存储，则不要使用此类。

build(string $optionKey, string $action): Store

• @param string $optionKey 选项表中保存所有队列通知的键。
• @param string $action 粘性通知的 AJAX 请求 'action' 属性。
• @return Store

$store = Factory::build('my_unique_option_key', 'my_unique_action');

常见问题解答

我能实现自己的通知类吗？

当然！只需实现 NoticeInterface。

查看类 Notice 和 StickyNotice 以及它们的测试，例如 StoreInterface 的示例实现。

如果您想创建一个开源包来帮助他人做这个，请新建一个问题，让我们知道，我们很乐意帮助您。

我能使用除 wp_option 表之外的其他存储方案吗？

当然！WP Admin Notices 数据存储是完全可替换的，并且一直是这样。

要实现自定义存储

1. 实现 StoreInterface
2. 将您的自定义存储传递给 Notifier

class MyCustomStore implements StoreInterface
{
  // Implements all the required methods.
}

$store = new MyCustomStore;
$action = 'my_unique_action';
$notifier = new Notifier($action, $store);

add_action('admin_notices', [$notifier, 'renderNotices']);
add_action("wp_ajax_$action", [$notifier, 'dismissNotice']);
add_action('admin_footer', [$notifier, 'renderScript']);

查看 Store 类和 StoreTest 以获取 StoreInterface 的示例实现。

如果您想创建一个开源包来帮助他人做这个，请新建一个问题，让我们知道，我们很乐意帮助您。

这是一个插件吗？

不，这是一个应该成为您插件一部分的包。

当 wp.org 插件团队告诉我清理 vendor 文件夹时，我该怎么做？

使用以下命令重新安装包。此包仅将必要文件导出到 dist。

$ composer install --no-dev --prefer-dist --optimize-autoloader

两个不同的插件可以同时使用这个包吗？

是的，如果您将所有 WP Admin Notices 类放在您自己的命名空间下，以避免类名冲突。

• imposter-plugin
• mozart

你有使用这个包的演示插件吗？

您可以通过以下方式安装此演示插件

$ wp plugin install https://github.com/TypistTech/wp-admin-notices/archive/nightly.zip --activate

查看 wp-admin-notices.php。我们用它进行验收测试。

你有使用这个包的真实生活示例吗？

就是这里

• 晴天
• WP Cloudflare Guard

在此处添加您的插件 这里

这看起来很棒。我在哪里可以找到更多类似的好东西？

• 在 Typist Tech 的 博客 上的文章
• 在 wp.org 上的 Tang Rufus 的 WordPress 插件
• 在 Typist Tech 的 GitHub 个人资料 上的更多项目
• 关注 Typist Tech 的通讯
• 关注 Tang Rufus 的 Twitter 账户
• 雇佣 Tang Rufus 来构建您的下一个精彩网站

支持

喜欢 wp-admin-notices？帮助我维护它，这里的捐赠可以帮助。

为什么不雇用我？

准备好接受自由职业的 WordPress 工作。通过此联系表单或通过电子邮件info@typist.tech联系我

想以其他方式帮忙吗？想成为赞助商吗？

联系： Tang Rufus

开发

要设置可工作的开发版本，您应该运行以下命令

$ composer create-project --keep-vcs --no-install typisttech/wp-admin-notices:dev-master
$ cd wp-admin-notices
$ composer install

运行测试

WP Admin Notices 在 Codeception 上运行测试，并依赖 wp-browser 提供WordPress集成。在测试之前，您需要在本地安装WordPress并添加一个 codeception.yml 文件。请参阅 *.suite.example.yml 以获取 Local by Flywheel 配置示例。

实际运行测试

$ composer test

我们还测试了所有PHP文件是否符合 PSR-2: 编码风格指南 以及部分 WordPress 编码标准。

使用 $ composer check-style 检查代码风格。

反馈

请提供反馈！ 我们希望使这个包在尽可能多的项目中都有用。请提交一个 问题 并指出您喜欢和不喜欢的地方，或者fork该项目并提供建议。 任何问题都不算小。

变更日志

请参阅 变更日志 以获取有关最近更改的更多信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 wp-admin-notices@typist.tech 联系，而不是使用问题跟踪器。

贡献

请参阅 贡献指南 和 行为准则 以获取详细信息。

致谢

WP Admin Notices 是一个 Typist Tech 项目，由自由职业开发者 Tang Rufus 维护。

所有贡献者的完整列表可以在 这里 找到。

许可证

WP Admin Notices 遵循 GPLv2 (或更高版本) 许可，由 自由软件基金会 提供。请参阅 许可证文件 获取更多信息。