/wp-content/plugins/google-analytics-for-wordpress/includes/deprecated.php

  1<?php
  2/**
  3 * Deprecated functions.
  4 *
  5 * Contains the functions used to deprecate functions and
  6 * hooks in MonsterInsights, as well as the deprecated functions
  7 * and hooks themselves, where possible.
  8 * 
  9 * @since 6.0.0
 10 *
 11 * @package MonsterInsights
 12 * @subpackage Deprecated
 13 * @author  Chris Christoff
 14 */
 15
 16// Exit if accessed directly
 17if ( ! defined( 'ABSPATH' ) ) {
 18	exit;
 19}
 20
 21/**
 22 * Fires functions attached to a deprecated filter hook.
 23 *
 24 * When a filter hook is deprecated, the apply_filters() call is replaced with
 25 * apply_filters_deprecated(), which triggers a deprecation notice and then fires
 26 * the original filter hook. Note, this is a copy of WordPress core's _apply_filters_deprecated
 27 * function, that we've copied into MonsterInsights so that we can use it on WordPress
 28 * versions older than 6.0.0 (when it was introduced to core). If we ever bump our
 29 * minimum WP version requirements above 6.0.0, we'll remove this function.
 30 *
 31 * @since 6.0.0
 32 * @access private
 33 *
 34 * @see _apply_filters_deprecated()
 35 *
 36 * @param string $tag         The name of the filter hook.
 37 * @param array  $args        Array of additional function arguments to be passed to apply_filters().
 38 * @param string $version     The version of WordPress that deprecated the hook.
 39 * @param string $message     Optional. A message regarding the change. Default null.
 40 */
 41function _monsterinsights_apply_filters_deprecated( $tag, $args, $version, $message = null ) {
 42		if ( ! has_filter( $tag ) ) {
 43				return $args[0];
 44		}
 45
 46		_monsterinsights_deprecated_hook( $tag, $version, $message );
 47
 48		return apply_filters_ref_array( $tag, $args );
 49}
 50
 51/**
 52 * Fires functions attached to a deprecated action hook.
 53 *
 54 * When an action hook is deprecated, the do_action() call is replaced with
 55 * do_action_deprecated(), which triggers a deprecation notice and then fires
 56 * the original hook. Note, this is a copy of WordPress core's _do_action_deprecated
 57 * function, that we've copied into MonsterInsights so that we can use it on WordPress
 58 * versions older than 6.0.0 (when it was introduced to core). If we ever bump our
 59 * minimum WP version requirements above 6.0.0, we'll remove this function.
 60 *
 61 * @since 6.0.0
 62 * @access private
 63 *
 64 * @see _do_action_deprecated()
 65 *
 66 * @param string $tag         The name of the action hook.
 67 * @param array  $args        Array of additional function arguments to be passed to do_action().
 68 * @param string $version     The version of WordPress that deprecated the hook.
 69 * @param string $message     Optional. A message regarding the change.
 70 */
 71function _monsterinsights_do_action_deprecated( $tag, $args, $version, $message = null ) {
 72		if ( ! has_action( $tag ) ) {
 73				return;
 74		}
 75
 76		_monsterinsights_deprecated_hook( $tag, $version, $message );
 77
 78		do_action_ref_array( $tag, $args );
 79}
 80
 81/**
 82 * Marks a deprecated action or filter hook as deprecated and throws a notice.
 83 *
 84 * Use the {@see 'deprecated_hook_run'} action to get the backtrace describing where
 85 * the deprecated hook was called.
 86 *
 87 * Default behavior is to trigger a user error if `WP_DEBUG` is true.
 88 *
 89 * This function is called by the do_action_deprecated() and apply_filters_deprecated()
 90 * functions, and so generally does not need to be called directly.
 91 *
 92 * Note, this is a copy of WordPress core's _deprecated_hook
 93 * function, that we've copied into MonsterInsights so that we can use it on WordPress
 94 * versions older than 6.0.0 (when it was introduced to core). If we ever bump our
 95 * minimum WP version requirements above 6.0.0, we'll remove this function.
 96 *
 97 * @since 6.0.0
 98 * @access private
 99 *
100 * @param string $hook        The hook that was used.
101 * @param string $version     The version of WordPress that deprecated the hook.
102 * @param string $message     Optional. A message regarding the change.
103 */
104function _monsterinsights_deprecated_hook( $hook, $version, $message = null ) {
105	/**
106	 * Fires when a deprecated hook is called.
107	 *
108	 * @since 6.0.0
109	 *
110	 * @param string $hook        The hook that was called.
111	 * @param string $version     The version of MonsterInsights that deprecated the hook used.
112	 * @param string $message     A message regarding the change.
113	 */
114	do_action( 'deprecated_hook_run', $hook, $version, $message );
115 
116	/**
117	 * Filters whether to trigger deprecated hook errors.
118	 *
119	 * @since 6.0.0
120	 *
121	 * @param bool $trigger Whether to trigger deprecated hook errors. Requires
122	 *                      `WP_DEBUG` to be defined true.
123	 */
124	if ( ( WP_DEBUG && apply_filters( 'deprecated_hook_trigger_error', true ) ) || monsterinsights_is_debug_mode() ) {
125		$message = empty( $message ) ? '' : ' ' . $message;
126		trigger_error( sprintf( esc_html__( '%1$s is %3$sdeprecated%4$s since MonsterInsights version %2$s!', 'google-analytics-for-wordpress' ), $hook, $version, '<strong>', '</strong>' ) . esc_html ( $message ) );
127	}
128}
129
130/**
131 * Marks a function as deprecated and informs when it has been used.
132 *
133 * There is a hook monsterinsights_deprecated_function_run that will be called that can be used
134 * to get the backtrace up to what file and function called the deprecated
135 * function. Based on the one in EDD core.
136 *
137 * The current behavior is to trigger a user error if WP_DEBUG is true.
138 *
139 * This function is to be used in every function that is deprecated.
140 *
141 * @since 6.0.0
142 * @access private
143 *
144 * @uses do_action() Calls 'monsterinsights_deprecated_function_run' and passes the function name, what to use instead,
145 *   and the version the function was deprecated in.
146 * @uses apply_filters() Calls 'monsterinsights_deprecated_function_trigger_error' and expects boolean value of true to do
147 *   trigger or false to not trigger error.
148 *   
149 * @param string  $function    The function that was called
150 * @param string  $version     The version of WordPress that deprecated the function
151 * @param array   $backtrace   Optional. Contains stack backtrace of deprecated function
152 * @return void
153 */
154function _monsterinsights_deprecated_function( $function, $version, $backtrace = null ) {
155
156	/**
157	 * Deprecated Function Action.
158	 *
159	 * Allow plugin run an action on the use of a 
160	 * deprecated function. This could be used to
161	 * feed into an error logging program or file.
162	 *
163	 * @since 6.0.0
164	 * 
165	 * @param string  $function    The function that was called.
166	 * @param string  $version     The version of WordPress that deprecated the function.
167	 * @param array   $backtrace   Optional. Contains stack backtrace of deprecated function.
168	 */	
169	do_action( 'deprecated_function_run', $function, $version, $backtrace );
170
171	/**
172	 * Filters whether to trigger an error for deprecated functions.
173	 *
174	 * @since 6.0.0
175	 *
176	 * @param bool $trigger Whether to trigger the error for deprecated functions. Default true.
177	 */
178	if ( ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) || monsterinsights_is_debug_mode() ) {
179		trigger_error( sprintf( esc_html__( '%1$s is %3$sdeprecated%4$s since MonsterInsights version %2$s.', 'google-analytics-for-wordpress' ), $function, $version, '<strong>', '</strong>' ) );
180		trigger_error( print_r( $backtrace, 1 ) );// Limited to previous 1028 characters, but since we only need to move back 1 in stack that should be fine.
181		// Alternatively we could dump this to a file.
182	}
183}
184
185/**
186 * Marks something as deprecated.
187 *
188 * The current behavior is to trigger a user error if WP_DEBUG is true.
189 *
190 * @since 6.0.0
191 * @access private
192 *
193 * @uses apply_filters() Calls 'monsterinsights_deprecated_trigger_error' and expects boolean value of true to do
194 *   trigger or false to not trigger error.
195 *
196 * @param string  $message     Deprecation message shown.
197 * @return void
198 */
199function _monsterinsights_deprecated( $message ) {
200
201	/**
202	 * Deprecated Message Filter.
203	 *
204	 * Allow plugin to filter the deprecated message.
205	 *
206	 * @since 6.0.0
207	 * 
208	 * @param string $message Error message.
209	 */	
210	do_action( 'monsterinsights_deprecated_run', $message );
211
212	$show_errors = current_user_can( 'manage_options' );
213
214	/**
215	 * Deprecated Error Trigger.
216	 *
217	 * Allow plugin to filter the output error trigger.
218	 *
219	 * @since 6.0.0
220	 * 
221	 * @param bool $show_errors Whether to show errors.
222	 */
223	$show_errors = apply_filters( 'monsterinsights_deprecated_trigger_error', $show_errors );
224	if ( ( WP_DEBUG && $show_errors ) || monsterinsights_is_debug_mode() ) {
225		trigger_error( esc_html( $message ) );
226	}
227}
228
229
230/**
231 * Start Deprecated Actions & Filters. 
232 *
233 * These backwards compatibility fixes may be removed at any time.
234 * Users/Developers are encouraged to update their code as soon as possible.
235 */
236