Ticket #43621: 43621.once.diff

src/wp-includes/plugin.php

@@ -115 +115 @@
 }
 
 /**
+ * Hook a function or method to a specific filter callback that is only run once.
+ *
+ * The added $function_to_add will only be run once and removed from the filter.
+ *
+ * @since 5.0
+ * @see add_filter
+ */
+function add_filter_once( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
+        $result = add_filter( $tag, $function_to_add, $priority, $accepted_args );
+
+        // Add a remove action immediately after our $function_to_add has run.
+        add_filter( $tag, '_remove_filter_once', $priority );
+
+        return $result;
+}
+
+/**
+ * Callback that removes an ephemeral filter (via add_filter_once)
+ * immediately after its execution.
+ *
+ * @since 5.0
+ * @see add_filter_once
+ * @internal
+ */
+function _remove_filter_once() {
+        global $wp_filter;
+
+        $tag               = current_filter();
+        $current_filter    = $wp_filter[ $tag ];
+        $current_priority  = $current_filter->current_priority();
+        $previous_callback = $current_filter->previous_callback();
+
+        // Remove the callback that has to be run once.
+        remove_filter( $tag, $previous_callback['function'], $current_priority );
+
+        // Remove the remove filter :) ... Filterception.
+        remove_filter( $tag, __FUNCTION__, $current_priority );
+
+        if ( func_num_args() ) {
+                // If this is a filter return the result.
+                return func_get_arg( 0 );
+        }
+}
+
+/**
  * Check if any filter has been registered for a hook.
  *
  * @since 2.5.0
@@ -407 +452 @@
 }
 
 /**
+ * Hook a function or method to a specific action callback that is only run once.
+ *
+ * The added $function_to_add will only be run once and removed from the action.
+ *
+ * @since 5.0
+ * @see add_action
+ */
+function add_action_once( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
+        return add_filter_once( $tag, $function_to_add, $priority, $accepted_args );
+}
+
+/**
  * Execute functions hooked on a specific action hook.
  *
  * This function invokes all functions attached to action hook `$tag`. It is

tests/phpunit/tests/filters.php

@@ -380 +380 @@
                 global $wp_filter;
                 $this->current_priority = $wp_filter['the_content']->current_priority();
         }
+
+        /**
+         * @ticket 43621
+         */
+        public function test_add_filter_once() {
+                add_filter_once( 'test_filter_once', '__return_true' );
+
+                $this->assertTrue( apply_filters( 'test_filter_once', false ) );
+                $this->assertFalse( apply_filters( 'test_filter_once', false ) );
+        }
+
+        /**
+         * @ticket 43621
+         */
+        public function test_add_action_once() {
+                global $_add_action_once_counter;
+                $_add_action_once_counter = 0;
+
+                add_action_once( 'test_filter_once', array( $this, '_add_action_once_increment' ) );
+
+                do_action( 'test_filter_once' );
+
+                $this->assertEquals( 1, $_add_action_once_counter );
+
+                do_action( 'test_filter_once' );
+
+                $this->assertEquals( 1, $_add_action_once_counter );
+        }
+
+        public function _add_action_once_increment() {
+                global $_add_action_once_counter;
+                $_add_action_once_counter++;
+        }
 }