polylang / include / language-deprecated.php

language-deprecated.php in Polylang 3.7.2, at include/language-deprecated.php

257 lines 7.1 KB

Raw Download Zip

1	<?php
2	/**
3	* @package Polylang
4	*/
5
6	/**
7	* Holds everything related to deprecated properties of `PLL_Language`.
8	*
9	* @since 3.4
10	*/
11	abstract class PLL_Language_Deprecated {
12
13	/**
14	* List of deprecated term properties and related arguments to use with `get_tax_prop()`.
15	*
16	* @private
17	*
18	* @var string[][]
19	*/
20	public const DEPRECATED_TERM_PROPERTIES = array(
21	'term_taxonomy_id' => array( 'language', 'term_taxonomy_id' ),
22	'count' => array( 'language', 'count' ),
23	'tl_term_id' => array( 'term_language', 'term_id' ),
24	'tl_term_taxonomy_id' => array( 'term_language', 'term_taxonomy_id' ),
25	'tl_count' => array( 'term_language', 'count' ),
26	);
27
28	/**
29	* List of deprecated URL properties and related getter to use.
30	*
31	* @private
32	*
33	* @var string[]
34	*/
35	public const DEPRECATED_URL_PROPERTIES = array(
36	'home_url' => 'get_home_url',
37	'search_url' => 'get_search_url',
38	);
39
40	/**
41	* Returns a language term property value (term ID, term taxonomy ID, or count).
42	*
43	* @since 3.4
44	*
45	* @param string $taxonomy_name Name of the taxonomy.
46	* @param string $prop_name Name of the property: 'term_taxonomy_id', 'term_id', 'count'.
47	* @return int
48	*
49	* @phpstan-param non-empty-string $taxonomy_name
50	* @phpstan-param 'term_taxonomy_id'\|'term_id'\|'count' $prop_name
51	* @phpstan-return int<0, max>
52	*/
53	abstract public function get_tax_prop( $taxonomy_name, $prop_name );
54
55	/**
56	* Returns language's home URL. Takes care to render it dynamically if no cache is allowed.
57	*
58	* @since 3.4
59	*
60	* @return string Language home URL.
61	*
62	* @phpstan-return non-empty-string
63	*/
64	abstract public function get_home_url();
65
66	/**
67	* Returns language's search URL. Takes care to render it dynamically if no cache is allowed.
68	*
69	* @since 3.4
70	*
71	* @return string Language search URL.
72	*
73	* @phpstan-return non-empty-string
74	*/
75	abstract public function get_search_url();
76
77	/**
78	* Throws a depreciation notice if someone tries to get one of the following properties:
79	* `term_taxonomy_id`, `count`, `tl_term_id`, `tl_term_taxonomy_id` or `tl_count`.
80	*
81	* Backward compatibility with Polylang < 3.4.
82	*
83	* @since 3.4
84	*
85	* @param string $property Property to get.
86	* @return mixed Required property value.
87	*/
88	public function __get( $property ) {
89	// Deprecated property.
90	if ( $this->is_deprecated_term_property( $property ) ) {
91	$this->deprecated_property(
92	$property,
93	sprintf(
94	"get_tax_prop( '%s', '%s' )",
95	self::DEPRECATED_TERM_PROPERTIES[ $property ][0],
96	self::DEPRECATED_TERM_PROPERTIES[ $property ][1]
97	)
98	);
99
100	return $this->get_deprecated_term_property( $property );
101	}
102
103	if ( $this->is_deprecated_url_property( $property ) ) {
104	$this->deprecated_property( $property, "get_{$property}()" );
105
106	return $this->get_deprecated_url_property( $property );
107	}
108
109	// Undefined property.
110	if ( ! property_exists( $this, $property ) ) {
111	return null;
112	}
113
114	// The property is defined.
115	$ref = new ReflectionProperty( $this, $property );
116
117	// Public property.
118	if ( $ref->isPublic() ) {
119	return $this->{$property};
120	}
121
122	// Protected or private property.
123	$visibility = $ref->isPrivate() ? 'private' : 'protected';
124	$trace = debug_backtrace(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection, WordPress.PHP.DevelopmentFunctions.error_log_debug_backtrace
125	$file = $trace[0]['file'] ?? '';
126	$line = $trace[0]['line'] ?? 0;
127	trigger_error( // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
128	esc_html(
129	sprintf(
130	"Cannot access %s property %s::$%s in %s on line %d.\nError handler",
131	$visibility,
132	get_class( $this ),
133	$property,
134	$file,
135	$line
136	)
137	),
138	E_USER_ERROR
139	);
140	}
141
142	/**
143	* Checks for a deprecated property.
144	* Is triggered by calling `isset()` or `empty()` on inaccessible (protected or private) or non-existing properties.
145	*
146	* Backward compatibility with Polylang < 3.4.
147	*
148	* @since 3.4
149	*
150	* @param string $property A property name.
151	* @return bool
152	*/
153	public function __isset( $property ) {
154	return $this->is_deprecated_term_property( $property ) \|\| $this->is_deprecated_url_property( $property );
155	}
156
157	/**
158	* Tells if the given term property is deprecated.
159	*
160	* @since 3.4
161	* @see PLL_Language::DEPRECATED_TERM_PROPERTIES for the list of deprecated properties.
162	*
163	* @param string $property A property name.
164	* @return bool
165	*
166	* @phpstan-assert-if-true key-of<PLL_Language::DEPRECATED_TERM_PROPERTIES> $property
167	*/
168	protected function is_deprecated_term_property( $property ) {
169	return array_key_exists( $property, self::DEPRECATED_TERM_PROPERTIES );
170	}
171
172	/**
173	* Returns a deprecated term property's value.
174	*
175	* @since 3.4
176	* @see PLL_Language::DEPRECATED_TERM_PROPERTIES for the list of deprecated properties.
177	*
178	* @param string $property A property name.
179	* @return int
180	*
181	* @phpstan-param key-of<PLL_Language::DEPRECATED_TERM_PROPERTIES> $property
182	* @phpstan-return int<0, max>
183	*/
184	protected function get_deprecated_term_property( $property ) {
185	return $this->get_tax_prop(
186	self::DEPRECATED_TERM_PROPERTIES[ $property ][0],
187	self::DEPRECATED_TERM_PROPERTIES[ $property ][1]
188	);
189	}
190
191	/**
192	* Tells if the given URL property is deprecated.
193	*
194	* @since 3.4
195	* @see PLL_Language::DEPRECATED_URL_PROPERTIES for the list of deprecated properties.
196	*
197	* @param string $property A property name.
198	* @return bool
199	*
200	* @phpstan-assert-if-true key-of<PLL_Language::DEPRECATED_URL_PROPERTIES> $property
201	*/
202	protected function is_deprecated_url_property( $property ) {
203	return array_key_exists( $property, self::DEPRECATED_URL_PROPERTIES );
204	}
205
206	/**
207	* Returns a deprecated URL property's value.
208	*
209	* @since 3.4
210	* @see PLL_Language::DEPRECATED_URL_PROPERTIES for the list of deprecated properties.
211	*
212	* @param string $property A property name.
213	* @return string
214	*
215	* @phpstan-param key-of<PLL_Language::DEPRECATED_URL_PROPERTIES> $property
216	* @phpstan-return non-empty-string
217	*/
218	protected function get_deprecated_url_property( $property ) {
219	return $this->{self::DEPRECATED_URL_PROPERTIES[ $property ]}();
220	}
221
222	/**
223	* Triggers a deprecated an error for a deprecated property.
224	*
225	* @since 3.4
226	*
227	* @param string $property Deprecated property name.
228	* @param string $replacement Method or property name to use instead.
229	* @return void
230	*/
231	private function deprecated_property( $property, $replacement ) {
232	/**
233	* Filters whether to trigger an error for deprecated properties.
234	*
235	* The filter name is intentionally not prefixed to use the same as WordPress
236	* in case it is added in the future.
237	*
238	* @since 3.4
239	*
240	* @param bool $trigger Whether to trigger the error for deprecated properties. Default true.
241	*/
242	if ( ! WP_DEBUG \|\| ! apply_filters( 'deprecated_property_trigger_error', true ) ) {
243	return;
244	}
245
246	trigger_error( // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
247	sprintf(
248	"Class property %1\$s::\$%2\$s is deprecated, use %1\$s::%3\$s instead.\nError handler",
249	esc_html( get_class( $this ) ),
250	esc_html( $property ),
251	esc_html( $replacement )
252	),
253	E_USER_DEPRECATED
254	);
255	}
256	}
257