/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 
  17. if ( ! defined( 'ABSPATH' ) ) { 
  18. exit; 
  19.  
  20. /** 
  21. * Fires functions attached to a deprecated filter hook. 
  22. * 
  23. * When a filter hook is deprecated, the apply_filters() call is replaced with 
  24. * apply_filters_deprecated(), which triggers a deprecation notice and then fires 
  25. * the original filter hook. Note, this is a copy of WordPress core's _apply_filters_deprecated 
  26. * function, that we've copied into MonsterInsights so that we can use it on WordPress 
  27. * versions older than 6.0.0 (when it was introduced to core). If we ever bump our 
  28. * minimum WP version requirements above 6.0.0, we'll remove this function. 
  29. * 
  30. * @since 6.0.0 
  31. * @access private 
  32. * 
  33. * @see _apply_filters_deprecated() 
  34. * 
  35. * @param string $tag The name of the filter hook. 
  36. * @param array $args Array of additional function arguments to be passed to apply_filters(). 
  37. * @param string $version The version of WordPress that deprecated the hook. 
  38. * @param string $message Optional. A message regarding the change. Default null. 
  39. */ 
  40. function _monsterinsights_apply_filters_deprecated( $tag, $args, $version, $message = null ) { 
  41. if ( ! has_filter( $tag ) ) { 
  42. return $args[0]; 
  43.  
  44. _monsterinsights_deprecated_hook( $tag, $version, $message ); 
  45.  
  46. return apply_filters_ref_array( $tag, $args ); 
  47.  
  48. /** 
  49. * Fires functions attached to a deprecated action hook. 
  50. * 
  51. * When an action hook is deprecated, the do_action() call is replaced with 
  52. * do_action_deprecated(), which triggers a deprecation notice and then fires 
  53. * the original hook. Note, this is a copy of WordPress core's _do_action_deprecated 
  54. * function, that we've copied into MonsterInsights so that we can use it on WordPress 
  55. * versions older than 6.0.0 (when it was introduced to core). If we ever bump our 
  56. * minimum WP version requirements above 6.0.0, we'll remove this function. 
  57. * 
  58. * @since 6.0.0 
  59. * @access private 
  60. * 
  61. * @see _do_action_deprecated() 
  62. * 
  63. * @param string $tag The name of the action hook. 
  64. * @param array $args Array of additional function arguments to be passed to do_action(). 
  65. * @param string $version The version of WordPress that deprecated the hook. 
  66. * @param string $message Optional. A message regarding the change. 
  67. */ 
  68. function _monsterinsights_do_action_deprecated( $tag, $args, $version, $message = null ) { 
  69. if ( ! has_action( $tag ) ) { 
  70. return; 
  71.  
  72. _monsterinsights_deprecated_hook( $tag, $version, $message ); 
  73.  
  74. do_action_ref_array( $tag, $args ); 
  75.  
  76. /** 
  77. * Marks a deprecated action or filter hook as deprecated and throws a notice. 
  78. * 
  79. * Use the {@see 'deprecated_hook_run'} action to get the backtrace describing where 
  80. * the deprecated hook was called. 
  81. * 
  82. * Default behavior is to trigger a user error if `WP_DEBUG` is true. 
  83. * 
  84. * This function is called by the do_action_deprecated() and apply_filters_deprecated() 
  85. * functions, and so generally does not need to be called directly. 
  86. * 
  87. * Note, this is a copy of WordPress core's _deprecated_hook 
  88. * function, that we've copied into MonsterInsights so that we can use it on WordPress 
  89. * versions older than 6.0.0 (when it was introduced to core). If we ever bump our 
  90. * minimum WP version requirements above 6.0.0, we'll remove this function. 
  91. * 
  92. * @since 6.0.0 
  93. * @access private 
  94. * 
  95. * @param string $hook The hook that was used. 
  96. * @param string $version The version of WordPress that deprecated the hook. 
  97. * @param string $message Optional. A message regarding the change. 
  98. */ 
  99. function _monsterinsights_deprecated_hook( $hook, $version, $message = null ) { 
  100. /** 
  101. * Fires when a deprecated hook is called. 
  102. * 
  103. * @since 6.0.0 
  104. * 
  105. * @param string $hook The hook that was called. 
  106. * @param string $version The version of MonsterInsights that deprecated the hook used. 
  107. * @param string $message A message regarding the change. 
  108. */ 
  109. do_action( 'deprecated_hook_run', $hook, $version, $message ); 
  110.  
  111. /** 
  112. * Filters whether to trigger deprecated hook errors. 
  113. * 
  114. * @since 6.0.0 
  115. * 
  116. * @param bool $trigger Whether to trigger deprecated hook errors. Requires 
  117. * `WP_DEBUG` to be defined true. 
  118. */ 
  119. if ( ( WP_DEBUG && apply_filters( 'deprecated_hook_trigger_error', true ) ) || monsterinsights_is_debug_mode() ) { 
  120. $message = empty( $message ) ? '' : ' ' . $message; 
  121. 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 ) ); 
  122.  
  123. /** 
  124. * Marks a function as deprecated and informs when it has been used. 
  125. * 
  126. * There is a hook monsterinsights_deprecated_function_run that will be called that can be used 
  127. * to get the backtrace up to what file and function called the deprecated 
  128. * function. Based on the one in EDD core. 
  129. * 
  130. * The current behavior is to trigger a user error if WP_DEBUG is true. 
  131. * 
  132. * This function is to be used in every function that is deprecated. 
  133. * 
  134. * @since 6.0.0 
  135. * @access private 
  136. * 
  137. * @uses do_action() Calls 'monsterinsights_deprecated_function_run' and passes the function name, what to use instead,  
  138. * and the version the function was deprecated in. 
  139. * @uses apply_filters() Calls 'monsterinsights_deprecated_function_trigger_error' and expects boolean value of true to do 
  140. * trigger or false to not trigger error. 
  141. *  
  142. * @param string $function The function that was called 
  143. * @param string $version The version of WordPress that deprecated the function 
  144. * @param array $backtrace Optional. Contains stack backtrace of deprecated function 
  145. * @return void 
  146. */ 
  147. function _monsterinsights_deprecated_function( $function, $version, $backtrace = null ) { 
  148.  
  149. /** 
  150. * Deprecated Function Action. 
  151. * 
  152. * Allow plugin run an action on the use of a  
  153. * deprecated function. This could be used to 
  154. * feed into an error logging program or file. 
  155. * 
  156. * @since 6.0.0 
  157. *  
  158. * @param string $function The function that was called. 
  159. * @param string $version The version of WordPress that deprecated the function. 
  160. * @param array $backtrace Optional. Contains stack backtrace of deprecated function. 
  161. */  
  162. do_action( 'deprecated_function_run', $function, $version, $backtrace ); 
  163.  
  164. /** 
  165. * Filters whether to trigger an error for deprecated functions. 
  166. * 
  167. * @since 6.0.0 
  168. * 
  169. * @param bool $trigger Whether to trigger the error for deprecated functions. Default true. 
  170. */ 
  171. if ( ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) || monsterinsights_is_debug_mode() ) { 
  172. 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>' ) ); 
  173. 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. 
  174. // Alternatively we could dump this to a file. 
  175.  
  176. /** 
  177. * Marks something as deprecated. 
  178. * 
  179. * The current behavior is to trigger a user error if WP_DEBUG is true. 
  180. * 
  181. * @since 6.0.0 
  182. * @access private 
  183. * 
  184. * @uses apply_filters() Calls 'monsterinsights_deprecated_trigger_error' and expects boolean value of true to do 
  185. * trigger or false to not trigger error. 
  186. * 
  187. * @param string $message Deprecation message shown. 
  188. * @return void 
  189. */ 
  190. function _monsterinsights_deprecated( $message ) { 
  191.  
  192. /** 
  193. * Deprecated Message Filter. 
  194. * 
  195. * Allow plugin to filter the deprecated message. 
  196. * 
  197. * @since 6.0.0 
  198. *  
  199. * @param string $message Error message. 
  200. */  
  201. do_action( 'monsterinsights_deprecated_run', $message ); 
  202.  
  203. $show_errors = current_user_can( 'manage_options' ); 
  204.  
  205. /** 
  206. * Deprecated Error Trigger. 
  207. * 
  208. * Allow plugin to filter the output error trigger. 
  209. * 
  210. * @since 6.0.0 
  211. *  
  212. * @param bool $show_errors Whether to show errors. 
  213. */ 
  214. $show_errors = apply_filters( 'monsterinsights_deprecated_trigger_error', $show_errors ); 
  215. if ( ( WP_DEBUG && $show_errors ) || monsterinsights_is_debug_mode() ) { 
  216. trigger_error( esc_html( $message ) ); 
  217.  
  218.  
  219. /** 
  220. * Start Deprecated Actions & Filters.  
  221. * 
  222. * These backwards compatibility fixes may be removed at any time. 
  223. * Users are encouraged to update their code as soon as possible. 
  224. */ 
  225.  
  226.  
  227. /** 
  228. * Deprecated Filter: 'yst-ga-filter-api-limit'. 
  229. *  
  230. * Allow people to change the max results value in the API calls. Default value is 1000 results per call. 
  231. * 
  232. * @param int $limit Number of rows to request at most in API calls. Default 300. 
  233. * @return int Number of rows to request at most in API calls. 
  234. */ 
  235. function monsterinsights_yst_ga_filter_api_limit( $limit ) { 
  236. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_reporting_get_max_api_limit</code>' ); 
  237. return _monsterinsights_apply_filters_deprecated( 'yst-ga-filter-api-limit', array( $limit ), '6.0.0', $message ); 
  238. add_filter( 'monsterinsights_reporting_get_max_api_limit', 'monsterinsights_yst_ga_filter_api_limit' ); 
  239.  
  240. /** 
  241. * Deprecated Filter: 'yst_ga_track_super_admin'. 
  242. *  
  243. * Allows filtering if the Super admin should be tracked in a multi-site setup. Default false. 
  244. * 
  245. * @param bool $track Whether to track super admins. Default false. 
  246. * @return bool Whether to track super admins. Default false. 
  247. */ 
  248. function monsterinsights_yst_ga_track_super_admin( $track ) { 
  249. $track = ! $track; // invert track as in Yoast it defaulted to track super admins 
  250. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_track_super_admins</code>' ); 
  251. return _monsterinsights_apply_filters_deprecated( 'yst_ga_track_super_admin', array( $track ), '6.0.0', $message ); 
  252. add_filter( 'monsterinsights_track_super_admins', 'monsterinsights_yst_ga_track_super_admin' ); 
  253.  
  254.  
  255. /** 
  256. * Deprecated Action: 'yst_tracking'. 
  257. *  
  258. * Allows output before the analytics and ga.js tracking output. 
  259. */ 
  260. function monsterinsights_yst_tracking() { 
  261. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_tracking_before{_$mode}</code>' ); 
  262. _monsterinsights_do_action_deprecated( 'yst_tracking', array(), '6.0.0', $message ); 
  263. add_action( 'monsterinsights_tracking_before_ga', 'monsterinsights_yst_tracking' ); 
  264. add_action( 'monsterinsights_tracking_before_analytics', 'monsterinsights_yst_tracking' ); 
  265.  
  266. /** 
  267. * Deprecated Filter: 'yoast-ga-push-array-ga-js'. 
  268. *  
  269. * Allows filtering of the commands to push. 
  270. * 
  271. * @param array $options GA.js options. 
  272. * @return array GA.js options. 
  273. */ 
  274. function monsterinsights_yoast_ga_push_array_ga_js( $options ) { 
  275. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_frontend_tracking_options_analytics_end</code>' ); 
  276. return _monsterinsights_apply_filters_deprecated( 'yoast-ga-push-array-ga-js', array( $options ), '6.0.0', $message ); 
  277. add_filter( 'monsterinsights_frontend_tracking_options_ga_end', 'monsterinsights_yoast_ga_push_array_ga_js' ); 
  278.  
  279. /** 
  280. * Deprecated Filter: 'yoast-ga-push-array-universal'. 
  281. *  
  282. * Allows filtering of the commands to push. 
  283. * 
  284. * @param array $options analytics.js options. 
  285. * @return array Analytics.js options. 
  286. */ 
  287. function monsterinsights_yoast_ga_push_array_universal( $options ) { 
  288. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_frontend_tracking_options_analytics_end</code>' ); 
  289. return _monsterinsights_apply_filters_deprecated( 'yoast-ga-push-array-universal', array( $options ), '6.0.0', $message ); 
  290. add_filter( 'monsterinsights_frontend_tracking_options_analytics_end', 'monsterinsights_yoast_ga_push_array_universal' ); 
  291.  
  292. /** 
  293. * Deprecated Filter: 'yst_ga_filter_push_vars'. 
  294. *  
  295. * Allow adding to the $options variables before scripts are required. 
  296. * 
  297. * @param array $options analytics.js options. 
  298. * @return array Analytics.js options. 
  299. */ 
  300. function monsterinsights_yst_ga_filter_push_vars( $options ) { 
  301. if ( ! has_filter('yst_ga_filter_push_vars' ) ) { 
  302. return $options; 
  303. } else { 
  304. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_frontend_tracking_options_analytics_before_scripts</code>' ); 
  305. _monsterinsights_deprecated_hook( 'yst_ga_filter_push_vars', '6.0.0', $message ); 
  306.  
  307. $i = 0; 
  308. while ( true ) { 
  309. if ( empty( $options[ 'yst_ga_filter_push_vars_' . $i ] ) ) { 
  310. $options[ 'yst_ga_filter_push_vars_' . $i ] = apply_filters( 'yst_ga_filter_push_vars', $options );  
  311. break; 
  312. } else { 
  313. $i++; 
  314. return $options; 
  315. add_filter( 'monsterinsights_frontend_tracking_options_analytics_before_scripts', 'monsterinsights_yst_ga_filter_push_vars' ); 
  316.  
  317.  
  318. /** 
  319. * Deprecated Filter: 'yst-ga-filter-ga-config'. 
  320. *  
  321. * Allow filtering of the GA app. 
  322. * 
  323. * @param array $config GA App config. 
  324. * @return array GA App config. 
  325. */ 
  326. function monsterinsights_yst_ga_filter_ga_config( $config ) { 
  327. $message = sprintf( __( 'Use %s instead.', 'google-analytics-for-wordpress' ), '<code>monsterinsights_{lite/pro}_google_app_config</code>' ); 
  328. return _monsterinsights_apply_filters_deprecated( 'yst-ga-filter-ga-config', array( $config ), '6.0.0', $message ); 
  329. add_filter( 'monsterinsights_lite_google_app_config', 'monsterinsights_yst_ga_filter_ga_config' ); 
  330. add_filter( 'monsterinsights_pro_google_app_config', 'monsterinsights_yst_ga_filter_ga_config' ); 
.