elementor / modules / dev-tools / deprecation.php

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

370 lines 9.5 KB

Raw Download Zip

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