README

Perique - 插件生命周期

PinkCrab Perique 框架的一个模块，它使得在插件生命周期（激活、停用等）中的各种事件期间添加订阅者变得简单。

要求
Perique 插件框架 2.0.*
Wordpress 5.9+（从 WP5.9 测试到 WP6.2）
PHP 7.4+（从 PHP7.4 测试到 PHP8.2）

为什么？

简单OOP方法处理WordPress插件生命周期事件，如激活、停用和卸载。

连接到现有的Perique插件框架实例，以使用DI容器和其他共享服务。（请注意，由于这些钩子的触发方式，您可能无法完全访问DI自定义规则，请阅读以下更多详细信息。）

设置

要安装，您可以使用composer

$ composer require pinkcrab/perique-plugin-lifecycle

安装模块

这必须与Perique一起启动才能使用。这可以在您的插件主文件中轻松完成。

// file ../wp-content/plugins/acme_plugin/plugin.php

// Boot the app as normal
$app = (new App_Factory())
    ->default_setup()
    ->module(
        Plugin_Life_Cycle::class, 
        fn(Plugin_Life_Cycle $module): Plugin_Life_Cycle => $module
            ->plugin_base_file(__FILE__) // Optional
            ->event(SomeEvent::class)
            ->event('Foo\Some_Class_Name')
     )
    ->boot();

您可以将plugin_base_file作为主插件文件的路径传递，或者如果为空，将假定它是创建应用程序实例使用的文件。

所有事件都可以传递其类名，应该是完整命名空间，或者作为类名的字符串。

事件类型

您可以为以下3个事件编写监听器。每个监听器都将实现一个接口，该接口需要一个run()方法。

激活

所有类都必须实现PinkCrab\Plugin_Lifecycle\State_Event\Activation接口。

class Create_Option_On_Activation implements Activation {
    public function run(): void{
        update_option('plugin_activated', true);
    }
}

当插件被激活时将运行此操作

停用

所有类都必须实现PinkCrab\Plugin_Lifecycle\State_Event\Deactivation接口。

这些事件在调用时将静默失败，因此如果您希望捕获并处理任何错误/异常，应在事件运行方法中完成。

class Update_Option_On_Deactivation implements Deactivation {
    public function run(): void{
        try{
            update_option('plugin_activated', false);
        } catch( $th ){
            Something::send_some_error_email("Deactivation event 'FOO' threw exception during run()", $th->getMessage());
        }
    }
}

当插件被停用时将运行此操作

卸载

所有类都必须实现PinkCrab\Plugin_Lifecycle\State_Event\Uninstall接口。

我们将自动捕获任何异常并静默失败。如果您希望以不同的方式处理，请在自己的代码中捕获它们。

class Delete_Option_On_Uninstall implements Uninstall {
    public function run(): void{
        try{
            delete_option('plugin_activated');
        } catch( $th ){
            // Do something rather than let it be silently caught above!
        }
    }
}

当插件被卸载时将运行此操作

时间安排

事件在调用init钩子之前触发，因此当这些事件运行时，Perique只部分启动。这意味着您将能够访问DI_Container和App_Config，但只能直接添加的自定义规则，通过钩子使用第三方添加的任何规则将不可用。尽量使事件尽可能简单，以避免错误。

扩展

可以创建其他模块，用于添加更多事件并在finalise()方法调用前后触发其他操作。如果您希望添加更多事件或触发其他操作，这将很有用。

添加事件

您可以使用 Plugin_Life_Cycle::STATE_EVENTS 过滤器来添加额外的方法。

常量 Plugin_Life_Cycle::STATE_EVENTS = 'PinkCrab\Plugin_Lifecycle\State_Events'

add_filter(
    Plugin_Life_Cycle::STATE_EVENTS,
    function( array $events ): array {
        $events[] = SomeEvent::class;
        return $events;
    }
);

您还可以使用 Plugin_Life_Cycle::EVENT_LIST 过滤器在事件与 DI 容器构建完成后添加额外的事件。

常量 Plugin_Life_Cycle::EVENT_LIST = 'PinkCrab\Plugin_Lifecycle\Event_List'

add_filter(
    Plugin_Life_Cycle::EVENT_LIST,
    function( array $events ): array {
        $events[] = new SomeEventInstance();
        $events[] = $this->container->create(SomeOtherInstance::class);
        return $events;
    }
);

在最终化前触发操作

您可以使用 Plugin_Life_Cycle::PRE_FINALISE 过滤器在调用 finalise() 方法之前触发操作。

常量 Plugin_Life_Cycle::PRE_FINALISE = 'PinkCrab\Plugin_Lifecycle\Pre_Finalise'

add_action(
    Plugin_Life_Cycle::PRE_FINALISE,
    function( Plugin_Life_Cycle $module ): void {
        // Do something before finalise is called.
    }
);

在最终化后触发操作

您可以使用 Plugin_Life_Cycle::POST_FINALISE 过滤器在调用 finalise() 方法之后触发操作。

常量 Plugin_Life_Cycle::POST_FINALISE = 'PinkCrab\Plugin_Lifecycle\Post_Finalise'

add_action(
    Plugin_Life_Cycle::POST_FINALISE,
    function( Plugin_Life_Cycle $module ): void {
        // Do something after finalise is called.
    }
);

变更日志

• 2.0.1 - 重新引入了从插件文件获取基本路径的功能（如果没有定义，感谢 @hibernius）并更新了开发依赖。
• 2.0.0 - 更新以支持 Perique V2 并实现了新的模块系统。
• 1.0.0 - 跳过
• 0.2.1 - 更新了开发依赖和 GH 管道。
• 0.2.0 - 改进了卸载事件的处理并更新了所有开发依赖。
• 0.1.1 - 在主控制器中添加了 get_app()
• 0.1.0 - 初始版本