├── advanced-hooks-api.php
├── class-r-hook-handler.php
├── composer.json
└── readme.md


/advanced-hooks-api.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | /*
  3 | Plugin Name: Advanced Hooks API
  4 | Plugin URI: https://github.com/Rarst/advanced-hooks-api
  5 | Description: Set of (experimental) wrappers that allow to hook more elaborate events without coding intermediary functions.
  6 | Author: Andrey "Rarst" Savchenko
  7 | Author URI: http://www.rarst.net/
  8 | Version:
  9 | License Notes: MIT
 10 | 
 11 | Copyright (c) 2012 Andrey "Rarst" Savchenko
 12 | 
 13 | Permission is hereby granted, free of charge, to any person obtaining a copy of this
 14 | software and associated documentation files (the "Software"), to deal in the Software
 15 | without restriction, including without limitation the rights to use, copy, modify, merge,
 16 | publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
 17 | to whom the Software is furnished to do so, subject to the following conditions:
 18 | 
 19 | The above copyright notice and this permission notice shall be included in all copies
 20 | or substantial portions of the Software.
 21 | 
 22 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 23 | INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 24 | PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
 25 | FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 26 | OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 27 | DEALINGS IN THE SOFTWARE.
 28 | */
 29 | 
 30 | if ( ! class_exists( 'R_Hook_Handler' ) ) {
 31 | 
 32 | 	require dirname( __FILE__ ) . '/class-r-hook-handler.php';
 33 | 
 34 | 	/**
 35 | 	 * @param string   $tag
 36 | 	 * @param callback $callback
 37 | 	 * @param int      $priority
 38 | 	 * @param null     $args one or more arguments to pass to hooked function.
 39 | 	 *
 40 | 	 * @return bool
 41 | 	 */
 42 | 	function add_action_with_args( $tag, $callback, $priority = 10, $args = null ) {
 43 | 
 44 | 		$args = array_slice( func_get_args(), 3 );
 45 | 
 46 | 		return add_action( $tag, array( new R_Hook_Handler( $args, $callback ), 'action' ), $priority, 1 );
 47 | 	}
 48 | 
 49 | 	/**
 50 | 	 * @param string       $tag
 51 | 	 * @param callback     $callback
 52 | 	 * @param int          $priority
 53 | 	 * @param null         $args
 54 | 	 */
 55 | 	function remove_action_with_args( $tag, $callback, $priority = 10, $args = null ) {
 56 | 
 57 | 		$args = array_slice( func_get_args(), 3 );
 58 | 
 59 | 		R_Hook_Handler::remove_action( $tag, $priority, $args, 'action', $callback );
 60 | 	}
 61 | 
 62 | 	/**
 63 | 	 * @param string $tag
 64 | 	 * @param mixed  $return value to override filter with
 65 | 	 * @param int    $priority
 66 | 	 *
 67 | 	 * @return bool
 68 | 	 */
 69 | 	function add_filter_return( $tag, $return, $priority = 10 ) {
 70 | 
 71 | 		return add_filter( $tag, array( new R_Hook_Handler( $return ), 'filter' ), $priority, 0 );
 72 | 	}
 73 | 
 74 | 	/**
 75 | 	 * @param string $tag
 76 | 	 * @param mixed  $return
 77 | 	 * @param int    $priority
 78 | 	 */
 79 | 	function remove_filter_return( $tag, $return, $priority = 10 ) {
 80 | 
 81 | 		R_Hook_Handler::remove_action( $tag, $priority, $return, 'filter' );
 82 | 	}
 83 | 
 84 | 	/**
 85 | 	 * @param string $tag
 86 | 	 * @param mixed  $prepend value to concatenate at start of filtered string or unshift to start of filtered array
 87 | 	 * @param int    $priority
 88 | 	 *
 89 | 	 * @return bool
 90 | 	 */
 91 | 	function add_filter_prepend( $tag, $prepend, $priority = 10 ) {
 92 | 
 93 | 		return add_filter( $tag, array( new R_Hook_Handler( $prepend ), 'prepend' ), $priority, 1 );
 94 | 	}
 95 | 
 96 | 	/**
 97 | 	 * @param string $tag
 98 | 	 * @param mixed  $prepend
 99 | 	 * @param int    $priority
100 | 	 */
101 | 	function remove_filter_prepend( $tag, $prepend, $priority = 10 ) {
102 | 
103 | 		R_Hook_Handler::remove_action( $tag, $priority, $prepend, 'prepend' );
104 | 	}
105 | 
106 | 	/**
107 | 	 * @param string $tag
108 | 	 * @param mixed  $append value to concatenate at end of filtered string or append to end of filtered array
109 | 	 * @param int    $priority
110 | 	 *
111 | 	 * @return bool
112 | 	 */
113 | 	function add_filter_append( $tag, $append, $priority = 10 ) {
114 | 
115 | 		return add_filter( $tag, array( new R_Hook_Handler( $append ), 'append' ), $priority, 1 );
116 | 	}
117 | 
118 | 	/**
119 | 	 * @param string $tag
120 | 	 * @param mixed  $append
121 | 	 * @param int    $priority
122 | 	 */
123 | 	function remove_filter_append( $tag, $append, $priority = 10 ) {
124 | 
125 | 		R_Hook_Handler::remove_action( $tag, $priority, $append, 'append' );
126 | 	}
127 | 
128 | 	/**
129 | 	 * @param string $tag
130 | 	 * @param string $search  substring to search or array key
131 | 	 * @param string $replace string to replace substring or array value with
132 | 	 * @param int    $priority
133 | 	 *
134 | 	 * @return bool
135 | 	 */
136 | 	function add_filter_replace( $tag, $search, $replace, $priority = 10 ) {
137 | 
138 | 		return add_filter( $tag, array( new R_Hook_Handler( compact( 'search', 'replace' ) ), 'replace' ), $priority );
139 | 	}
140 | 
141 | 	/**
142 | 	 * @param string $tag
143 | 	 * @param string $search
144 | 	 * @param string $replace
145 | 	 * @param int    $priority
146 | 	 */
147 | 	function remove_filter_replace( $tag, $search, $replace, $priority = 10 ) {
148 | 
149 | 		R_Hook_Handler::remove_action( $tag, $priority, compact( 'search', 'replace' ), 'replace' );
150 | 	}
151 | 
152 | 	/**
153 | 	 * Add filter to only run once.
154 | 	 *
155 | 	 * @param string   $tag
156 | 	 * @param callback $callback
157 | 	 * @param int      $priority
158 | 	 * @param int      $accepted_args
159 | 	 *
160 | 	 * @return bool
161 | 	 */
162 | 	function add_filter_once( $tag, $callback, $priority = 10, $accepted_args = 1 ) {
163 | 
164 | 		return add_action( $tag, array( new R_Hook_Handler( compact( 'priority', 'accepted_args' ), $callback ), 'once' ), $priority, $accepted_args );
165 | 	}
166 | 
167 | 	/**
168 | 	 * Remove filter that runs once.
169 | 	 *
170 | 	 * @param string   $tag
171 | 	 * @param callback $callback
172 | 	 * @param int      $priority
173 | 	 * @param int      $accepted_args
174 | 	 */
175 | 	function remove_filter_once( $tag, $callback, $priority = 10, $accepted_args = 1 ) {
176 | 
177 | 		R_Hook_Handler::remove_action( $tag, $priority, compact( 'priority', 'accepted_args' ), 'once', $callback );
178 | 	}
179 | 
180 | 	/**
181 | 	 * Add action that only runs once.
182 | 	 *
183 | 	 * @param string   $tag
184 | 	 * @param callback $callback
185 | 	 * @param int      $priority
186 | 	 * @param int      $accepted_args
187 | 	 *
188 | 	 * @return bool
189 | 	 */
190 | 	function add_action_once( $tag, $callback, $priority = 10, $accepted_args = 1 ) {
191 | 
192 | 		return add_filter_once( $tag, $callback, $priority, $accepted_args );
193 | 	}
194 | 
195 | 	/**
196 | 	 * Remove action that runs once.
197 | 	 *
198 | 	 * @param string   $tag
199 | 	 * @param callback $callback
200 | 	 * @param int      $priority
201 | 	 * @param int      $accepted_args
202 | 	 */
203 | 	function remove_action_once( $tag, $callback, $priority = 10, $accepted_args = 1 ) {
204 | 
205 | 		remove_filter_once( $tag, $callback, $priority, $accepted_args );
206 | 	}
207 | 
208 | 	/**
209 | 	 * @param array|string       $tags  hook and method name or array of names
210 | 	 * @param int                $priority
211 | 	 * @param int                $accepted_args
212 | 	 * @param bool|string|object $class false for auto, class name or object
213 | 	 *
214 | 	 * @return bool|void
215 | 	 */
216 | 	function add_method( $tags, $priority = 10, $accepted_args = 1, $class = false ) {
217 | 
218 | 		if ( empty( $class ) ) {
219 | 
220 | 			list( , $caller) = debug_backtrace();
221 | 
222 | 			if ( empty( $caller['class'] ) )
223 | 				return false;
224 | 
225 | 			$class = ( '->' == $caller['type'] ) ? $caller['object'] : $caller['class'];
226 | 		}
227 | 
228 | 		if ( ! is_array( $tags ) )
229 | 			$tags = array( $tags );
230 | 
231 | 		foreach ( $tags as $tag ) {
232 | 
233 | 			if ( method_exists( $class, $tag ) )
234 | 				add_action( $tag, array( $class, $tag ), $priority, $accepted_args );
235 | 		}
236 | 
237 | 		return true;
238 | 	}
239 | }


--------------------------------------------------------------------------------
/class-r-hook-handler.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | /**
  4 |  * Handler class for events in hooks.
  5 |  */
  6 | class R_Hook_Handler {
  7 | 
  8 | 	private $data;
  9 | 
 10 | 	/**
 11 | 	 * @var callback
 12 | 	 */
 13 | 	private $callback;
 14 | 
 15 | 	/**
 16 | 	 * @param mixed         $data
 17 | 	 * @param null|callback $callback
 18 | 	 */
 19 | 	function __construct( $data, $callback = null ) {
 20 | 
 21 | 		$this->data     = $data;
 22 | 		$this->callback = $callback;
 23 | 	}
 24 | 
 25 | 	/**
 26 | 	 * Executes callback with custom arguments, ignores what hook passes.
 27 | 	 *
 28 | 	 * @return mixed|null
 29 | 	 */
 30 | 	function action() {
 31 | 
 32 | 		call_user_func_array( $this->callback, $this->data );
 33 | 
 34 | 		// compatibility with filters
 35 | 		if ( func_num_args() )
 36 | 			return func_get_arg( 0 );
 37 | 
 38 | 		return null;
 39 | 	}
 40 | 
 41 | 	/**
 42 | 	 * Returns custom data to filter.
 43 | 	 *
 44 | 	 * @return mixed
 45 | 	 */
 46 | 	function filter() {
 47 | 
 48 | 		return $this->data;
 49 | 	}
 50 | 
 51 | 	/**
 52 | 	 * Searches and replaces data as array or substring, depending on passed filter value.
 53 | 	 *
 54 | 	 * @param mixed $input
 55 | 	 *
 56 | 	 * @return array|mixed
 57 | 	 */
 58 | 	function replace( $input ) {
 59 | 
 60 | 		if ( is_array( $input ) )
 61 | 			$input[$this->data['search']] = $this->data['replace'];
 62 | 		else
 63 | 			$input = str_replace( $this->data['search'], $this->data['replace'], $input );
 64 | 
 65 | 		return $input;
 66 | 	}
 67 | 
 68 | 	/**
 69 | 	 * Prepends data to array or string, passed by filter.
 70 | 	 *
 71 | 	 * @param mixed $input
 72 | 	 *
 73 | 	 * @return array|string
 74 | 	 */
 75 | 	function prepend( $input ) {
 76 | 
 77 | 		if ( is_array( $input ) ) {
 78 | 
 79 | 			if ( is_array( $this->data ) ) {
 80 | 
 81 | 				foreach ( array_reverse( $this->data ) as $value ) {
 82 | 
 83 | 					array_unshift( $input, $value );
 84 | 				}
 85 | 			}
 86 | 			else {
 87 | 
 88 | 				array_unshift( $input, $this->data );
 89 | 			}
 90 | 		}
 91 | 		else {
 92 | 
 93 | 			$input = $this->data . $input;
 94 | 		}
 95 | 
 96 | 		return $input;
 97 | 	}
 98 | 
 99 | 
100 | 	/**
101 | 	 * Appends data to array or string, passed by filter.
102 | 	 *
103 | 	 * @param mixed $input
104 | 	 *
105 | 	 * @return array|string
106 | 	 */
107 | 	function append( $input ) {
108 | 
109 | 		if ( is_array( $input ) ) {
110 | 
111 | 			if ( is_array( $this->data ) ) {
112 | 
113 | 				foreach ( $this->data as $value ) {
114 | 
115 | 					$input[] = $value;
116 | 				}
117 | 			}
118 | 			else {
119 | 
120 | 				$input[] = $this->data;
121 | 			}
122 | 		}
123 | 		else {
124 | 
125 | 			$input .= $this->data;
126 | 		}
127 | 
128 | 		return $input;
129 | 	}
130 | 
131 | 	/**
132 | 	 * Executes callback once and removes it from hook.
133 | 	 *
134 | 	 * @return mixed
135 | 	 */
136 | 	function once() {
137 | 
138 | 		remove_filter( current_filter(), array( $this, __FUNCTION__ ), $this->data['priority'] );
139 | 
140 | 		return call_user_func_array( $this->callback, array_slice( func_get_args(), 0, $this->data['accepted_args'] ) );
141 | 	}
142 | 
143 | 	/**
144 | 	 * Remove matching handlers from specified hook and priority.
145 | 	 *
146 | 	 * @param string      $tag
147 | 	 * @param int         $priority
148 | 	 * @param mixed       $data
149 | 	 * @param string      $method of handler class
150 | 	 * @param string|null $callback
151 | 	 */
152 | 	static function remove_action( $tag, $priority, $data, $method, $callback = null ) {
153 | 		
154 | 		global $wp_filter;
155 | 		
156 | 		foreach ( $wp_filter[$tag][$priority] as $event ) {
157 | 
158 | 			$function = $event['function'];
159 | 
160 | 			/**
161 | 			 * @var R_Hook_Handler $object
162 | 			 */
163 | 			if ( is_array( $function ) && is_a( $object = $function[0], __CLASS__ ) )
164 | 					$object->remove_if_match( $tag, $priority, $event['accepted_args'], $data, $method, $callback );
165 | 		}
166 | 	}
167 | 
168 | 	/**
169 | 	 * Unhook this instance from hook if data matches.
170 | 	 *
171 | 	 * @param string      $tag
172 | 	 * @param int         $priority
173 | 	 * @param int         $accepted_args
174 | 	 * @param mixed       $data
175 | 	 * @param string      $method of handler class
176 | 	 * @param string|null $callback
177 | 	 */
178 | 	function remove_if_match( $tag, $priority, $accepted_args, $data, $method, $callback = null ) {
179 | 
180 | 		if ( $data === $this->data && $callback === $this->callback )
181 | 			remove_action( $tag, array( $this, $method ), $priority, $accepted_args );
182 | 	}
183 | }


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 | 	"name"        : "rarst/advanced-hooks-api",
 3 | 	"description" : "Set of (experimental) wrappers that allow to hook more elaborate WordPress events without coding intermediary functions",
 4 | 	"keywords"    : ["wordpress"],
 5 | 	"type"        : "wordpress-plugin",
 6 | 	"homepage"    : "https://github.com/Rarst/advanced-hooks-api",
 7 | 	"license"     : "MIT",
 8 | 	"authors"     : [
 9 | 		{
10 | 			"name"    : "Andrey Savchenko",
11 | 			"email"   : "contact@rarst.net",
12 | 			"homepage": "http://www.Rarst.net/"
13 | 		}
14 | 	],
15 | 	"support"     : {
16 | 		"issues": "https://github.com/Rarst/advanced-hooks-api/issues"
17 | 	},
18 | 	"require"     : {
19 | 		"composer/installers": "~1.0"
20 | 	}
21 | }


--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
 1 | # Advanced WordPress Hooks API
 2 | 
 3 | Set of (experimental) wrappers that allow to hook more elaborate WordPress events without coding intermediary functions.
 4 | 
 5 | WordPress only operates with callbacks for actions and filters. That means that you always need to use callback, either:
 6 | 
 7 |  - provided by core (limited)
 8 |  - closures (messy)
 9 |  - coded by yourself (this - a lot)
10 | 
11 | This plugins offers number of custom `add_*` functions to hook more elaborate events:
12 | 
13 |  - `add_action_with_args()` - hook callback **and** arguments to run it with
14 |  - `add_filter_return()` - override filter with arbitrary value
15 |  - `add_filter_prepend()` and `add_filter_append()` - hook suffix/prefix values for filtered string and arrays
16 |  - `add_filter_replace()` - edit substrings or array values in filter
17 |  - `add_action_once()` and `add_filter_once()` - hook callback to only fire once
18 |  - `add_method()` - quickly add class methods to hooks of same name
19 | 
20 | Both implementation and set of functions are experimental.
21 | 
22 | # Changelog
23 | 
24 | ## 0.7
25 | 
26 | * _(enhancement)_ implemented `add_action_once()` and `add_filter_once()`, props Eric Mann
27 | 
28 | ## 0.6
29 | 
30 | * _(enhancement)_ changed license to MIT
31 | * _(enhancement)_ cleaned up coding style
32 | * _(enhancement)_ moved handler class to separate file
33 | * _(enhancement)_ implemented removing of handler from hooks
34 | * **(breaking change)** changed signatures to make priority optional
35 | 
36 | ## 0.5
37 | 
38 | * _(enhancement)_ new add_method() function
39 | * _(enhancement)_ more return points for better logic and compatibility
40 | 
41 | ## 0.4.1
42 | 
43 | * _(bugfix)_ action() method expected argument passed (to be compatible with filters), changed to func_get_arg()
44 | 
45 | ## 0.4
46 | 
47 | * Initial public repository release.
48 | 


--------------------------------------------------------------------------------