elementor / modules / dev-tools / deprecation.php

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

360 lines 9.3 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	} else {
217	// Hard deprecated.
218	$print_deprecated = true;
219	}
220
221	return $print_deprecated;
222	}
223
224	/**
225	* Deprecated Function
226	*
227	* Handles the deprecation process for functions.
228	*
229	* @since 3.1.0
230	*
231	* @param string $function
232	* @param string $version
233	* @param string $replacement Optional. Default is ''
234	* @param string $base_version Optional. Default is `null`
235	* @throws \Exception
236	*/
237	public function deprecated_function( $function, $version, $replacement = '', $base_version = null ) {
238	$print_deprecated = $this->check_deprecation( $function, $version, $replacement, $base_version );
239
240	if ( $print_deprecated ) {
241	// PHPCS - We need to echo special characters because they can exist in function calls.
242	_deprecated_function( $function, esc_html( $version ), $replacement ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
243	}
244	}
245
246	/**
247	* Deprecated Hook
248	*
249	* Handles the deprecation process for hooks.
250	*
251	* @since 3.1.0
252	*
253	* @param string $hook
254	* @param string $version
255	* @param string $replacement Optional. Default is ''
256	* @param string $base_version Optional. Default is `null`
257	* @throws \Exception
258	*/
259	public function deprecated_hook( $hook, $version, $replacement = '', $base_version = null ) {
260	$print_deprecated = $this->check_deprecation( $hook, $version, $replacement, $base_version );
261
262	if ( $print_deprecated ) {
263	_deprecated_hook( esc_html( $hook ), esc_html( $version ), esc_html( $replacement ) );
264	}
265	}
266
267	/**
268	* Deprecated Argument
269	*
270	* Handles the deprecation process for function arguments.
271	*
272	* @since 3.1.0
273	*
274	* @param string $argument
275	* @param string $version
276	* @param string $replacement
277	* @param string $message
278	* @throws \Exception
279	*/
280	public function deprecated_argument( $argument, $version, $replacement = '', $message = '' ) {
281	$print_deprecated = $this->check_deprecation( $argument, $version, $replacement );
282
283	if ( $print_deprecated ) {
284	$message = empty( $message ) ? '' : ' ' . $message;
285	// These arguments are escaped because they are printed later, and are not escaped when printed.
286	$error_message_args = [ esc_html( $argument ), esc_html( $version ) ];
287
288	if ( $replacement ) {
289	/* translators: 1: Function argument, 2: Elementor version number, 3: Replacement argument name. */
290	$translation_string = esc_html__( 'The %1$s argument is deprecated since version %2$s! Use %3$s instead.', 'elementor' );
291	$error_message_args[] = $replacement;
292	} else {
293	/* translators: 1: Function argument, 2: Elementor version number. */
294	$translation_string = esc_html__( 'The %1$s argument is deprecated since version %2$s!', 'elementor' );
295	}
296
297	trigger_error(
298	vsprintf(
299	// PHPCS - $translation_string is already escaped above.
300	$translation_string, // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
301	// PHPCS - $error_message_args is an array.
302	$error_message_args // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
303	) . esc_html( $message ),
304	E_USER_DEPRECATED
305	);
306	}
307	}
308
309	/**
310	* Do Deprecated Action
311	*
312	* A method used to run deprecated actions through Elementor's deprecation process.
313	*
314	* @since 3.1.0
315	*
316	* @param string $hook
317	* @param array $args
318	* @param string $version
319	* @param string $replacement
320	* @param null\|string $base_version
321	*
322	* @throws \Exception
323	*/
324	public function do_deprecated_action( $hook, $args, $version, $replacement = '', $base_version = null ) {
325	if ( ! has_action( $hook ) ) {
326	return;
327	}
328
329	$this->deprecated_hook( $hook, $version, $replacement, $base_version );
330
331	do_action_ref_array( $hook, $args );
332	}
333
334	/**
335	* Apply Deprecated Filter
336	*
337	* A method used to run deprecated filters through Elementor's deprecation process.
338	*
339	* @since 3.2.0
340	*
341	* @param string $hook
342	* @param array $args
343	* @param string $version
344	* @param string $replacement
345	* @param null\|string $base_version
346	*
347	* @return mixed
348	* @throws \Exception
349	*/
350	public function apply_deprecated_filter( $hook, $args, $version, $replacement = '', $base_version = null ) {
351	if ( ! has_action( $hook ) ) {
352	return $args;
353	}
354
355	$this->deprecated_hook( $hook, $version, $replacement, $base_version );
356
357	return apply_filters_ref_array( $hook, $args );
358	}
359	}
360