WordPress PHP类中正确enqueue脚本样式方法及报错修复

问题现象 #

使用过程中触发如下PHP提示：

Notice: Function wp_enqueue_script was called incorrectly. Scripts and styles should not be registered or enqueued until the wp_enqueue_scripts, admin_enqueue_scripts, or login_enqueue_scripts hooks. This notice was triggered by the fluid-player-js handle. 

触发报错的原始代码来自WordPress官方插件目录中已停更4年的Fluid Player插件，片段如下：

public static $index = 0;

private static function loadAssets() {
    wp_enqueue_script( 'fluid-player-js', self::FP_CDN_CURRENT_URL . '/fluidplayer.min.js', [], false, true);
    wp_enqueue_style('fluid-player-css', self::FP_CDN_CURRENT_URL . '/fluidplayer.min.css');
}

public static function init() {
    static::loadAssets();
    static::initShortcodeToJSMapping();

    add_shortcode('fluid-player', array('FluidPlayerPlugin', 'shortcodeSimple'));
    add_shortcode('fluid-player-extended', array('FluidPlayerPlugin', 'shortcodeExtended'));
    add_shortcode('fluid-player-html-block', array('FluidPlayerPlugin', 'shortcodeHtmlBlock'));
    add_shortcode('fluid-player-multi-res-video', array('FluidPlayerPlugin', 'shortcodeHtmlBlock'));

    // 禁用短代码内容的智能引号过滤
    add_filter('no_texturize_shortcodes', function () {
        $shortcodes[] = 'fluid-player-multi-res-video';
        $shortcodes[] = 'fluid-player-html-block';
        $shortcodes[] = 'fluid-player-extended';
        $shortcodes[] = 'fluid-player';

        return $shortcodes;
    });

    // 移除短代码内容的自动换行和段落标签，可能存在副作用
    remove_filter('the_content', 'wpautop');
    remove_filter('the_excerpt', 'wpautop');
}

报错原因 #

WordPress核心对脚本、样式的注册/入队时机有强制约束，不能在任意执行节点直接调用wp_enqueue_script()、wp_enqueue_style()，必须等WordPress运行到专门的资源入队钩子阶段才能执行相关操作。原始代码在init()方法中直接调用loadAssets()入队资源，执行时机远早于规定的入队钩子节点，因此触发系统提示。

WordPress类中入队资源的正确规则 #

• 前端公开页面加载的脚本、样式，必须挂载到wp_enqueue_scripts动作钩子执行
• 后台管理页面加载的脚本、样式，必须挂载到admin_enqueue_scripts动作钩子执行
• 登录页面加载的脚本、样式，必须挂载到login_enqueue_scripts动作钩子执行

修复方案 #

只需要修改init()方法中调用loadAssets()的逻辑，不要直接执行方法，而是将方法绑定到对应入队钩子即可。该插件为前端短代码播放器，资源仅需在前端加载，因此绑定到wp_enqueue_scripts钩子即可，修改后的init()方法如下：

public static function init() {
    // 替换原直接调用static::loadAssets()的逻辑，挂载到正确的入队钩子
    add_action('wp_enqueue_scripts', array('FluidPlayerPlugin', 'loadAssets'));
    static::initShortcodeToJSMapping();

    add_shortcode('fluid-player', array('FluidPlayerPlugin', 'shortcodeSimple'));
    add_shortcode('fluid-player-extended', array('FluidPlayerPlugin', 'shortcodeExtended'));
    add_shortcode('fluid-player-html-block', array('FluidPlayerPlugin', 'shortcodeHtmlBlock'));
    add_shortcode('fluid-player-multi-res-video', array('FluidPlayerPlugin', 'shortcodeHtmlBlock'));

    // 禁用短代码内容的智能引号过滤
    add_filter('no_texturize_shortcodes', function () {
        $shortcodes[] = 'fluid-player-multi-res-video';
        $shortcodes[] = 'fluid-player-html-block';
        $shortcodes[] = 'fluid-player-extended';
        $shortcodes[] = 'fluid-player';

        return $shortcodes;
    });

    // 移除短代码内容的自动换行和段落标签，可能存在副作用
    remove_filter('the_content', 'wpautop');
    remove_filter('the_excerpt', 'wpautop');
}

补充说明：如果后续需要给插件新增后台设置页的专属资源，再额外把对应资源加载逻辑挂载到admin_enqueue_scripts钩子即可，不要和前端资源混在一起加载，避免后台页面加载不必要的前端资源拖慢加载速度。

内容的提问来源于stack exchange，提问作者Mario Rossi