elementor / modules / dev-tools / deprecation.php

deprecation.php in Elementor Website Builder – more than just a page builder 4.1.0-dev1, at modules/dev-tools/deprecation.php

369 lines 9.7 KB

Raw Download Zip

1	<?php
2	namespace Elementor\Modules\DevTools;
3
4	use Elementor\Utils;
5
6	if ( ! defined( 'ABSPATH' ) ) {
7	exit; // Exit if accessed directly.
8	}
9
10	class Deprecation {
11	const SOFT_VERSIONS_COUNT = 4;
12	const HARD_VERSIONS_COUNT = 8;
13
14	private $current_version = null;
15	private $soft_deprecated_notices = [];
16
17	public function __construct( $current_version ) {
18	$this->current_version = $current_version;
19	}
20
21	public function get_settings() {
22	return [
23	'soft_notices' => $this->soft_deprecated_notices,
24	'soft_version_count' => self::SOFT_VERSIONS_COUNT,
25	'hard_version_count' => self::HARD_VERSIONS_COUNT,
26	'current_version' => ELEMENTOR_VERSION,
27	];
28	}
29
30	/**
31	* Get total of major.
32	*
33	* Since `get_total_major` cannot determine how much really versions between 2.9.0 and 3.3.0 if there is 2.10.0 version for example,
34	* versions with major2 more then 9 will be added to total.
35	*
36	* @since 3.1.0
37	*
38	* @param array $parsed_version
39	*
40	* @return int
41	*/
42	public function get_total_major( $parsed_version ) {
43	$major1 = $parsed_version['major1'];
44	$major2 = $parsed_version['major2'];
45	$major2 = $major2 > 9 ? 9 : $major2;
46	$minor = 0;
47
48	$total = intval( "{$major1}{$major2}{$minor}" );
49
50	if ( $total > 99 ) {
51	$total = $total / 10;
52	} else {
53	$total = intval( $total / 10 );
54	}
55
56	if ( $parsed_version['major2'] > 9 ) {
57	$total += $parsed_version['major2'] - 9;
58	}
59
60	return $total;
61	}
62
63	/**
64	* Get next version.
65	*
66	* @since 3.1.0
67	*
68	* @param string $version
69	* @param int $count
70	*
71	* @return string\|false
72	*/
73	public function get_next_version( $version, $count = 1 ) {
74	$version = $this->parse_version( $version );
75
76	if ( ! $version ) {
77	return false;
78	}
79
80	$version['total'] = $this->get_total_major( $version ) + $count;
81
82	$total = $version['total'];
83
84	if ( $total > 9 ) {
85	$version['major1'] = intval( $total / 10 );
86	$version['major2'] = $total % 10;
87	} else {
88	$version['major1'] = 0;
89	$version['major2'] = $total;
90	}
91
92	$version['minor'] = 0;
93
94	return $this->implode_version( $version );
95	}
96
97	/**
98	* Implode parsed version to string version.
99	*
100	* @since 3.1.0
101	*
102	* @param array $parsed_version
103	*
104	* @return string
105	*/
106	public function implode_version( $parsed_version ) {
107	$major1 = $parsed_version['major1'];
108	$major2 = $parsed_version['major2'];
109	$minor = $parsed_version['minor'];
110
111	return "{$major1}.{$major2}.{$minor}";
112	}
113
114	/**
115	* Parse to an informative array.
116	*
117	* @since 3.1.0
118	*
119	* @param string $version
120	*
121	* @return array\|false
122	*/
123	public function parse_version( $version ) {
124	$version_explode = explode( '.', $version );
125	$version_explode_count = count( $version_explode );
126
127	if ( $version_explode_count < 3 \|\| $version_explode_count > 4 ) {
128	trigger_error( 'Invalid Semantic Version string provided' );
129
130	return false;
131	}
132
133	list( $major1, $major2, $minor ) = $version_explode;
134
135	$result = [
136	'major1' => intval( $major1 ),
137	'major2' => intval( $major2 ),
138	'minor' => intval( $minor ),
139	];
140
141	if ( $version_explode_count > 3 ) {
142	$result['build'] = $version_explode[3];
143	}
144
145	return $result;
146	}
147
148	/**
149	* Compare two versions, result is equal to diff of major versions.
150	* Notice: If you want to compare between 2.9.0 and 3.3.0, and there is also a 2.10.0 version, you cannot get the right comparison
151	* Since $this->deprecation->get_total_major cannot determine how much really versions between 2.9.0 and 3.3.0.
152	*
153	* @since 3.1.0
154	*
155	* @param {string} $version1
156	* @param {string} $version2
157	*
158	* @return int\|false
159	*/
160	public function compare_version( $version1, $version2 ) {
161	$version1 = self::parse_version( $version1 );
162	$version2 = self::parse_version( $version2 );
163
164	if ( $version1 && $version2 ) {
165	$versions = [ &$version1, &$version2 ];
166
167	foreach ( $versions as &$version ) {
168	$version['total'] = self::get_total_major( $version );
169	}
170
171	return $version1['total'] - $version2['total'];
172	}
173
174	return false;
175	}
176
177	/**
178	* Check Deprecation
179	*
180	* Checks whether the given entity is valid. If valid, this method checks whether the deprecation
181	* should be soft (browser console notice) or hard (use WordPress' native deprecation methods).
182	*
183	* @since 3.1.0
184	*
185	* @param string $entity - The Deprecated entity (the function/hook itself)
186	* @param string $version
187	* @param string $replacement Optional
188	* @param string $base_version Optional. Default is `null`
189	*
190	* @return bool
191	* @throws \Exception Invalid deprecation.
192	*/
193	private function check_deprecation( $entity, $version, $replacement, $base_version = null ) {
194	if ( null === $base_version ) {
195	$base_version = $this->current_version;
196	}
197
198	$diff = $this->compare_version( $base_version, $version );
199
200	if ( false === $diff ) {
201	throw new \Exception( 'Invalid deprecation diff.' );
202	}
203
204	$print_deprecated = false;
205
206	if ( defined( 'WP_DEBUG' ) && WP_DEBUG && $diff <= self::SOFT_VERSIONS_COUNT ) {
207	// Soft deprecated.
208	if ( ! isset( $this->soft_deprecated_notices[ $entity ] ) ) {
209	$this->soft_deprecated_notices[ $entity ] = [
210	$version,
211	$replacement,
212	];
213	}
214
215	if ( Utils::is_elementor_debug() ) {
216	$print_deprecated = true;
217	}
218	}
219
220	return $print_deprecated;
221	}
222
223	/**
224	* Deprecated Function
225	*
226	* Handles the deprecation process for functions.
227	*
228	* @since 3.1.0
229	*
230	* @param string $function_name
231	* @param string $version
232	* @param string $replacement Optional. Default is ''
233	* @param string $base_version Optional. Default is `null`
234	* @throws \Exception Deprecation error.
235	*/
236	public function deprecated_function( $function_name, $version, $replacement = '', $base_version = null ) {
237	$print_deprecated = $this->check_deprecation( $function_name, $version, $replacement, $base_version );
238
239	if ( $print_deprecated ) {
240	// PHPCS - We need to echo special characters because they can exist in function calls.
241	_deprecated_function( $function_name, esc_html( $version ), $replacement ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
242	}
243	}
244
245	/**
246	* Deprecated Hook
247	*
248	* Handles the deprecation process for hooks.
249	*
250	* @param string $hook
251	* @param string $version
252	* @param string $replacement Optional. Default is ''
253	* @param string $base_version Optional. Default is `null`
254	* @throws \Exception Deprecation error.
255	* @since 3.1.0
256	*/
257	public function deprecated_hook( $hook, $version, $replacement = '', $base_version = null ) {
258	$print_deprecated = $this->check_deprecation( $hook, $version, $replacement, $base_version );
259
260	if ( $print_deprecated ) {
261	_deprecated_hook( esc_html( $hook ), esc_html( $version ), esc_html( $replacement ) );
262	}
263	}
264
265	/**
266	* Deprecated Argument
267	*
268	* Handles the deprecation process for function arguments.
269	*
270	* @since 3.1.0
271	*
272	* @param string $argument
273	* @param string $version
274	* @param string $replacement
275	* @param string $message
276	* @throws \Exception Deprecation error.
277	*/
278	public function deprecated_argument( $argument, $version, $replacement = '', $message = '' ) {
279	$print_deprecated = $this->check_deprecation( $argument, $version, $replacement );
280
281	if ( $print_deprecated ) {
282	$message = empty( $message ) ? '' : ' ' . $message;
283	// These arguments are escaped because they are printed later, and are not escaped when printed.
284	$error_message_args = [ esc_html( $argument ), esc_html( $version ) ];
285
286	if ( $replacement ) {
287	/* translators: 1: Function argument, 2: Elementor version number, 3: Replacement argument name. */
288	$translation_string = esc_html__( 'The %1$s argument is deprecated since version %2$s! Use %3$s instead.', 'elementor' );
289	$error_message_args[] = $replacement;
290	} else {
291	/* translators: 1: Function argument, 2: Elementor version number. */
292	$translation_string = esc_html__( 'The %1$s argument is deprecated since version %2$s!', 'elementor' );
293	}
294
295	trigger_error(
296	vsprintf(
297	// PHPCS - $translation_string is already escaped above.
298	$translation_string, // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
299	// PHPCS - $error_message_args is an array.
300	$error_message_args // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
301	) . esc_html( $message ),
302	E_USER_DEPRECATED
303	);
304	}
305	}
306
307	/**
308	* Do Deprecated Action
309	*
310	* A method used to run deprecated actions through Elementor's deprecation process.
311	*
312	* @param string $hook
313	* @param array $args
314	* @param string $version
315	* @param string $replacement
316	* @param null\|string $base_version
317	*
318	* @throws \Exception Deprecation error.
319	* @since 3.1.0
320	*/
321	public function do_deprecated_action( $hook, $args, $version, $replacement = '', $base_version = null ) {
322	if ( ! has_action( $hook ) ) {
323	return;
324	}
325
326	$this->deprecated_hook( $hook, $version, $replacement, $base_version );
327
328	do_action_ref_array( $hook, $args );
329	}
330
331	/**
332	* Apply Deprecated Filter
333	*
334	* A method used to run deprecated filters through Elementor's deprecation process.
335	*
336	* @param string $hook
337	* @param array $args
338	* @param string $version
339	* @param string $replacement
340	* @param null\|string $base_version
341	*
342	* @return mixed
343	* @throws \Exception Deprecation error.
344	* @since 3.2.0
345	*/
346	public function apply_deprecated_filter( $hook, $args, $version, $replacement = '', $base_version = null ) {
347	if ( ! has_action( $hook ) ) {
348	// `$args` should be an array, but in order to keep BC, we need to support non-array values.
349	if ( is_array( $args ) ) {
350	return $args[0] ?? null;
351	}
352
353	return $args;
354	}
355
356	// BC - See the comment above.
357	if ( ! is_array( $args ) ) {
358	$args = [ $args ];
359	}
360
361	// Avoid associative arrays.
362	$args = array_values( $args );
363
364	$this->deprecated_hook( $hook, $version, $replacement, $base_version );
365
366	return apply_filters_ref_array( $hook, $args );
367	}
368	}
369