README

WordPress插件API是第三方脚本能够注入WordPress生命周期的绝佳方式。多亏了WordPress动作和过滤器（统称为“钩子”），主题和插件开发者可以引入各种新的功能。

然而，有时WordPress钩子的“全有或全无”的心态可能会让开发者陷入困境，因为他们只想让回调运行一次。例如，也许你的主题有一个简单的add_top_story_class()函数，它将.top-story添加到类列表中。如果你只想将其应用到循环中的第一篇文章，你可能需要编写如下代码

<?php while ( $query->have_posts() ) : $query->the_post(); ?>

  <?php if ( 0 === $query->current_post ) add_filter( 'post_class', 'add_top_story_class' ); ?>

  <article <?php post_class(); ?>>
    <h2><?php the_title(); ?></h2>
    <?php the_excerpt(); ?>
  </article>

  <?php remove_filter( 'post_class', 'add_top_story_class' ); ?>

<?php endwhile; ?>

真糟糕！我们需要根据当前文章的索引有条件地添加一个过滤器，然后在循环结束时移除过滤器以确保它不会应用到每篇文章。

使用 一次性回调，这会变得更加简洁

<?php while ( $query->have_posts() ) : $query->the_post(); ?>

  <?php add_filter_once( 'post_class', 'add_top_story_class' ); ?>

  <article <?php post_class(); ?>>
    <h2><?php the_title(); ?></h2>
    <?php the_excerpt(); ?>
  </article>

<?php endwhile; ?>

add_filter_once()函数将允许回调恰好运行一次，然后它会自动清理。

安装

安装此包的最佳方式是通过Composer

$ composer require stevegrunwell/one-time-callbacks

该包包含composer/installers包，使您可以控制包的安装位置。例如，如果您在WordPress插件中使用One-time Hooks，您可能希望将文件存储在includes/目录中。为此，请将以下内容添加到您的插件composer.json文件中

{
    "extra": {
        "installer-paths": {
            "includes/{$name}/": ["stevegrunwell/one-time-callbacks"]
        }
    }
}

然后，在您的插件内部，只需包含或引入文件

require_once __DIR__ . '/includes/one-time-callbacks/one-time-callbacks.php';

作为插件使用

如果您愿意，该包还包含必要的文件头，以作为WordPress插件使用。

下载或克隆包后，将one-time-callbacks.php移动到您的wp-content/mu-plugins/（推荐）或wp-content/plugins/目录中。如果您选择了常规插件目录，您需要通过WP Admin中的插件 › 已安装插件页面手动激活插件。

在插件或主题中打包

一次性回调被构建成可以轻松打包到WordPress插件或主题中，甚至是商业用途。

每个函数声明都被包裹在适当的function_exists()检查中，确保库的多个副本可以在同一WordPress环境中共存。

用法

一次性回调为WordPress提供以下函数

• add_action_once()
• add_filter_once()

add_action_once()

注册一个只运行一次的动作。

参数与add_action()相同，但此函数还会注册一个用于在第一个回调运行后立即移除它的第二个回调。

参数

(string) $hook

动作名称。

(callable) $callback

回调函数。

(int) $priority

可选。回调应执行的优先级。默认为10。

(int) $args

可选。回调函数期望的参数数量。默认为1。

返回值

与add_action()一样，此函数始终返回true。

add_filter_once()

注册一个只运行一次的过滤器。

参数与 add_filter() 相同，但此函数还会注册一个用于在运行后立即删除第一个回调的第二个回调。

参数

(string) $hook

动作名称。

(callable) $callback

回调函数。

(int) $priority

可选。回调应执行的优先级。默认为10。

(int) $args

可选。回调函数期望的参数数量。默认为1。

返回值

与 add_filter() 一样，此函数始终返回 true。

许可证

版权所有 2018 Steve Grunwell

在此特此授权，任何人未经费用即可获得此软件及其相关文档文件（以下简称“软件”）的副本，可无限制地使用软件，包括但不限于使用、复制、修改、合并、发布、分发、许可和/或出售软件的副本，并允许向软件提供者提供软件的人这样做，但必须遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不提供任何形式的保证，无论是明示的还是暗示的，包括但不限于适销性、针对特定目的的适用性和非侵权性。在任何情况下，作者或版权持有人不对任何索赔、损害或其他责任负责，无论该索赔、损害或其他责任是基于合同、侵权或其他法律，无论该索赔、损害或其他责任是否与软件或其使用或其他方式有关。