PluginProbe
Polylang / 2.2
Polylang v2.2
3.8.9 3.8.8 3.8.7 3.8.6 3.8.5 3.8.4 3.8.3 2.7 2.7.0.1 2.7.1 2.7.2 2.7.3 2.7.4 2.8 2.8.1 2.8.2 2.8.3 2.8.4 2.9 2.9.1 2.9.2 3.0 3.0.1 3.0.2 3.0.3 All 233 releases
← All changes | include/api.php +115 -179 3.0 → 2.2 View file →
@@ -1,113 +1,94 @@
1 1 <?php
2 -/**
3 - * @package Polylang
4 - */
5 2
6 3 /**
7 - * Template tag: displays the language switcher.
8 - * The function does nothing if used outside the frontend.
4 + * Template tag: displays the language switcher
9 5 *
10 - * @api
6 + * List of parameters accepted in $args:
7 + *
8 + * dropdown => displays a dropdown if set to 1, defaults to 0
9 + * echo => echoes the switcher if set to 1 ( default )
10 + * hide_if_empty => hides languages with no posts ( or pages ) if set to 1 ( default )
11 + * show_flags => shows flags if set to 1, defaults to 0
12 + * show_names => shows languages names if set to 1 ( default )
13 + * display_names_as => whether to display the language name or its slug, valid options are 'slug' and 'name', defaults to name
14 + * force_home => forces linking to the home page is set to 1, defaults to 0
15 + * hide_if_no_translation => hides the link if there is no translation if set to 1, defaults to 0
16 + * hide_current => hides the current language if set to 1, defaults to 0
17 + * post_id => if not null, link to translations of post defined by post_id, defaults to null
18 + * raw => set this to true to build your own custom language switcher, defaults to 0
19 + * item_spacing => whether to preserve or discard whitespace between list items, valid options are 'preserve' and 'discard', defaults to preserve
20 + *
11 21 * @since 0.5
12 22 *
13 - * @param array $args {
14 - * Optional array of arguments.
15 - *
16 - * @type int $dropdown The list is displayed as dropdown if set to 1, defaults to 0.
17 - * @type int $echo Echoes the list if set to 1, defaults to 1.
18 - * @type int $hide_if_empty Hides languages with no posts ( or pages ) if set to 1, defaults to 1.
19 - * @type int $show_flags Displays flags if set to 1, defaults to 0.
20 - * @type int $show_names Shows language names if set to 1, defaults to 1.
21 - * @type string $display_names_as Whether to display the language name or its slug, valid options are 'slug' and 'name', defaults to name.
22 - * @type int $force_home Will always link to the homepage in the translated language if set to 1, defaults to 0.
23 - * @type int $hide_if_no_translation Hides the link if there is no translation if set to 1, defaults to 0.
24 - * @type int $hide_current Hides the current language if set to 1, defaults to 0.
25 - * @type int $post_id Returns links to the translations of the post defined by post_id if set, defaults to not set.
26 - * @type int $raw Return a raw array instead of html markup if set to 1, defaults to 0.
27 - * @type string $item_spacing Whether to preserve or discard whitespace between list items, valid options are 'preserve' and 'discard', defaults to 'preserve'.
28 - * }
29 - * @return string|array Either the html markup of the switcher or the raw elements to build a custom language switcher.
23 + * @param array $args optional
24 + * @return null|string|array null if displaying, array if raw is requested, string otherwise
30 25 */
31 -function pll_the_languages( $args = array() ) {
32 - $switcher = new PLL_Switcher();
33 - return $switcher->the_languages( PLL()->links, $args );
26 +function pll_the_languages( $args = '' ) {
27 + if ( PLL() instanceof PLL_Frontend ) {
28 + $switcher = new PLL_Switcher;
29 + return $switcher->the_languages( PLL()->links, $args );
30 + }
31 + return '';
34 32 }
35 33
36 34 /**
37 - * Returns the current language on frontend.
38 - * Returns the language set in admin language filter on backend ( false if set to all languages ).
35 + * Returns the current language on frontend
36 + * Returns the language set in admin language filter on backend ( false if set to all languages )
39 37 *
40 - * @api
41 38 * @since 0.8.1
42 39 *
43 - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. Pass OBJECT constant to get the language object.
44 - * @return string|PLL_Language|false The requested field for the current language.
40 + * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
41 + * @return string|bool The requested field for the current language
45 42 */
46 43 function pll_current_language( $field = 'slug' ) {
47 - if ( OBJECT === $field ) {
48 - return PLL()->curlang;
49 - }
50 44 return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false;
51 45 }
52 46
53 47 /**
54 - * Returns the default language.
48 + * Returns the default language
55 49 *
56 - * @api
57 50 * @since 1.0
58 51 *
59 - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. Pass OBJECT constant to get the language object.
60 - * @return string|PLL_Language|false The requested field for the default language.
52 + * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
53 + * @return string The requested field for the default language
61 54 */
62 55 function pll_default_language( $field = 'slug' ) {
63 - if ( isset( PLL()->options['default_lang'] ) ) {
64 - $lang = PLL()->model->get_language( PLL()->options['default_lang'] );
65 - if ( $lang ) {
66 - if ( OBJECT === $field ) {
67 - return $lang;
68 - }
69 - return isset( $lang->$field ) ? $lang->$field : false;
70 - }
71 - }
72 - return false;
56 + return isset( PLL()->options['default_lang'] ) && ( $lang = PLL()->model->get_language( PLL()->options['default_lang'] ) ) && isset( $lang->$field ) ? $lang->$field : false;
73 57 }
74 58
75 59 /**
76 - * Among the post and its translations, returns the id of the post which is in the language represented by $lang.
60 + * Among the post and its translations, returns the id of the post which is in the language represented by $slug
77 61 *
78 - * @api
79 62 * @since 0.5
80 63 *
81 - * @param int $post_id Post id.
82 - * @param string $lang Optional language code, defaults to the current language.
83 - * @return int|false|null Post id of the translation if it exists, false otherwise, null if the current language is not defined yet.
64 + * @param int $post_id post id
65 + * @param string $slug optional language code, defaults to current language
66 + * @return int|false|null post id of the translation if exists, false otherwise, null if the current language is not defined yet
84 67 */
85 -function pll_get_post( $post_id, $lang = '' ) {
86 - return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->post->get( $post_id, $lang ) : null;
68 +function pll_get_post( $post_id, $slug = '' ) {
69 + return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->post->get( $post_id, $slug ) : null;
87 70 }
88 71
89 72 /**
90 - * Among the term and its translations, returns the id of the term which is in the language represented by $lang.
73 + * Among the term and its translations, returns the id of the term which is in the language represented by $slug
91 74 *
92 - * @api
93 75 * @since 0.5
94 76 *
95 - * @param int $term_id Term id.
96 - * @param string $lang Optional language code, defaults to the current language.
97 - * @return int|false|null Term id of the translation if it exists, false otherwise, null if the current language is not defined yet.
77 + * @param int $term_id term id
78 + * @param string $slug optional language code, defaults to current language
79 + * @return int|false|null term id of the translation if exists, false otherwise, null if the current language is not defined yet
98 80 */
99 -function pll_get_term( $term_id, $lang = '' ) {
100 - return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->term->get( $term_id, $lang ) : null;
81 +function pll_get_term( $term_id, $slug = '' ) {
82 + return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->term->get( $term_id, $slug ) : null;
101 83 }
102 84
103 85 /**
104 - * Returns the home url in a language.
86 + * Returns the home url in the current language
105 87 *
106 - * @api
107 88 * @since 0.8
108 89 *
109 - * @param string $lang Optional language code, defaults to the current language.
90 + * @param string $lang language code ( optional on frontend )
110 91 * @return string
111 92 */
112 93 function pll_home_url( $lang = '' ) {
113 94 if ( empty( $lang ) ) {
@@ -117,21 +98,18 @@
117 98 return empty( $lang ) ? home_url( '/' ) : PLL()->links->get_home_url( $lang );
118 99 }
119 100
120 101 /**
121 - * Registers a string for translation in the "strings translation" panel.
102 + * Registers a string for translation in the "strings translation" panel
122 103 *
123 - * @api
124 104 * @since 0.6
125 105 *
126 - * @param string $name A unique name for the string.
127 - * @param string $string The string to register.
128 - * @param string $context Optional, the group in which the string is registered, defaults to 'polylang'.
129 - * @param bool $multiline Optional, true if the string table should display a multiline textarea,
130 - * false if should display a single line input, defaults to false.
131 - * @return void
106 + * @param string $name a unique name for the string
107 + * @param string $string the string to register
108 + * @param string $context optional the group in which the string is registered, defaults to 'polylang'
109 + * @param bool $multiline optional wether the string table should display a multiline textarea or a single line input, defaults to single line
132 110 */
133 -function pll_register_string( $name, $string, $context = 'Polylang', $multiline = false ) {
111 +function pll_register_string( $name, $string, $context = 'polylang', $multiline = false ) {
134 112 if ( PLL() instanceof PLL_Admin_Base ) {
135 113 PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
136 114 }
137 115 }
@@ -136,28 +114,26 @@
136 114 }
137 115 }
138 116
139 117 /**
140 - * Translates a string ( previously registered with pll_register_string ).
118 + * Translates a string ( previously registered with pll_register_string )
141 119 *
142 - * @api
143 120 * @since 0.6
144 121 *
145 - * @param string $string The string to translate.
146 - * @return string The string translated in the current language.
122 + * @param string $string the string to translate
123 + * @return string the string translation in the current language
147 124 */
148 125 function pll__( $string ) {
149 - return is_scalar( $string ) ? __( $string, 'pll_string' ) : $string; // PHPCS:ignore WordPress.WP.I18n
126 + return is_scalar( $string ) ? __( $string, 'pll_string' ) : $string;
150 127 }
151 128
152 129 /**
153 130 * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
154 131 *
155 - * @api
156 132 * @since 2.1
157 133 *
158 - * @param string $string The string to translate.
159 - * @return string The string translated in the current language.
134 + * @param string $string the string to translate
135 + * @return string translation in the current language
160 136 */
161 137 function pll_esc_html__( $string ) {
162 138 return esc_html( pll__( $string ) );
163 139 }
@@ -164,13 +140,12 @@
164 140
165 141 /**
166 142 * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
167 143 *
168 - * @api
169 144 * @since 2.1
170 145 *
171 - * @param string $string The string to translate.
172 - * @return string The string translated in the current language.
146 + * @param string $string The string to translate
147 + * @return string
173 148 */
174 149 function pll_esc_attr__( $string ) {
175 150 return esc_attr( pll__( $string ) );
176 151 }
@@ -176,58 +151,50 @@
176 151 }
177 152
178 153 /**
179 154 * Echoes a translated string ( previously registered with pll_register_string )
180 - * It is an equivalent of _e() and is not escaped.
181 155 *
182 - * @api
183 156 * @since 0.6
184 157 *
185 - * @param string $string The string to translate.
186 - * @return void
158 + * @param string $string The string to translate
187 159 */
188 160 function pll_e( $string ) {
189 - echo pll__( $string ); // phpcs:ignore
161 + echo pll__( $string );
190 162 }
191 163
192 164 /**
193 165 * Echoes a translated string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
194 166 *
195 - * @api
196 167 * @since 2.1
197 168 *
198 - * @param string $string The string to translate.
199 - * @return void
169 + * @param string $string The string to translate
200 170 */
201 171 function pll_esc_html_e( $string ) {
202 - echo pll_esc_html__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
172 + echo pll_esc_html__( $string );
203 173 }
204 174
205 175 /**
206 176 * Echoes a translated a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
207 177 *
208 - * @api
209 178 * @since 2.1
210 179 *
211 - * @param string $string The string to translate.
212 - * @return void
180 + * @param string $string The string to translate
213 181 */
214 182 function pll_esc_attr_e( $string ) {
215 - echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
183 + echo pll_esc_attr__( $string );
216 184 }
217 185
218 186 /**
219 - * Translates a string ( previously registered with pll_register_string ).
187 + * Translates a string ( previously registered with pll_register_string )
220 188 *
221 - * @api
222 189 * @since 1.5.4
223 190 *
224 - * @param string $string The string to translate.
225 - * @param string $lang Language code.
226 - * @return string The string translated in the requested language.
191 + * @param string $string the string to translate
192 + * @param string $lang language code
193 + * @return string the string translation in the requested language
227 194 */
228 195 function pll_translate_string( $string, $lang ) {
229 - if ( PLL() instanceof PLL_Frontend && pll_current_language() == $lang ) {
196 + if ( pll_current_language() == $lang ) {
230 197 return pll__( $string );
231 198 }
232 199
233 200 if ( ! is_scalar( $string ) ) {
@@ -233,9 +200,9 @@
233 200 if ( ! is_scalar( $string ) ) {
234 201 return $string;
235 202 }
236 203
237 - static $cache; // Cache object to avoid loading the same translations object several times.
204 + static $cache; // Cache object to avoid loading the same translations object several times
238 205
239 206 if ( empty( $cache ) ) {
240 207 $cache = new PLL_Cache();
241 208 }
@@ -249,14 +216,13 @@
249 216 return $mo->translate( $string );
250 217 }
251 218
252 219 /**
253 - * Returns true if Polylang manages languages and translations for this post type.
220 + * Returns true if Polylang manages languages and translations for this post type
254 221 *
255 - * @api
256 222 * @since 1.0.1
257 223 *
258 - * @param string $post_type Post type name.
224 + * @param string $post_type Post type name
259 225 * @return bool
260 226 */
261 227 function pll_is_translated_post_type( $post_type ) {
262 228 return PLL()->model->is_translated_post_type( $post_type );
@@ -262,14 +228,13 @@
262 228 return PLL()->model->is_translated_post_type( $post_type );
263 229 }
264 230
265 231 /**
266 - * Returns true if Polylang manages languages and translations for this taxonomy.
232 + * Returns true if Polylang manages languages and translations for this taxonomy
267 233 *
268 - * @api
269 234 * @since 1.0.1
270 235 *
271 - * @param string $tax Taxonomy name.
236 + * @param string $tax Taxonomy name
272 237 * @return bool
273 238 */
274 239 function pll_is_translated_taxonomy( $tax ) {
275 240 return PLL()->model->is_translated_taxonomy( $tax );
@@ -275,20 +240,19 @@
275 240 return PLL()->model->is_translated_taxonomy( $tax );
276 241 }
277 242
278 243 /**
279 - * Returns the list of available languages.
244 + * Returns the list of available languages
280 245 *
281 - * @api
246 + * List of parameters accepted in $args:
247 + *
248 + * hide_empty => hides languages with no posts if set to true ( defaults to false )
249 + * fields => return only that field if set ( see PLL_Language for a list of fields )
250 + *
282 251 * @since 1.5
283 252 *
284 - * @param array $args {
285 - * Optional array of arguments.
286 - *
287 - * @type bool $hide_empty Hides languages with no posts if set to true ( defaults to false ).
288 - * @type string $fields Return only that field if set ( @see PLL_Language for a list of fields ), defaults to 'slug'.
289 - * }
290 - * @return string[]
253 + * @param array $args list of parameters
254 + * @return array
291 255 */
292 256 function pll_languages_list( $args = array() ) {
293 257 $args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
294 258 return PLL()->model->get_languages_list( $args );
@@ -294,16 +258,14 @@
294 258 return PLL()->model->get_languages_list( $args );
295 259 }
296 260
297 261 /**
298 - * Sets the post language.
262 + * Set the post language
299 263 *
300 - * @api
301 264 * @since 1.5
302 265 *
303 - * @param int $id Post id.
304 - * @param string $lang Language code.
305 - * @return void
266 + * @param int $id post id
267 + * @param string $lang language code
306 268 */
307 269 function pll_set_post_language( $id, $lang ) {
308 270 PLL()->model->post->set_language( $id, $lang );
309 271 }
@@ -308,16 +270,14 @@
308 270 PLL()->model->post->set_language( $id, $lang );
309 271 }
310 272
311 273 /**
312 - * Sets the term language.
274 + * Set the term language
313 275 *
314 - * @api
315 276 * @since 1.5
316 277 *
317 - * @param int $id Term id.
318 - * @param string $lang Language code.
319 - * @return void
278 + * @param int $id term id
279 + * @param string $lang language code
320 280 */
321 281 function pll_set_term_language( $id, $lang ) {
322 282 PLL()->model->term->set_language( $id, $lang );
323 283 }
@@ -322,15 +282,13 @@
322 282 PLL()->model->term->set_language( $id, $lang );
323 283 }
324 284
325 285 /**
326 - * Save posts translations.
286 + * Save posts translations
327 287 *
328 - * @api
329 288 * @since 1.5
330 289 *
331 - * @param int[] $arr An associative array of translations with language code as key and post id as value.
332 - * @return void
290 + * @param array $arr an associative array of translations with language code as key and post id as value
333 291 */
334 292 function pll_save_post_translations( $arr ) {
335 293 PLL()->model->post->save_translations( reset( $arr ), $arr );
336 294 }
@@ -337,13 +295,11 @@
337 295
338 296 /**
339 297 * Save terms translations
340 298 *
341 - * @api
342 299 * @since 1.5
343 300 *
344 - * @param int[] $arr An associative array of translations with language code as key and term id as value.
345 - * @return void
301 + * @param array $arr an associative array of translations with language code as key and term id as value
346 302 */
347 303 function pll_save_term_translations( $arr ) {
348 304 PLL()->model->term->save_translations( reset( $arr ), $arr );
349 305 }
@@ -348,16 +304,15 @@
348 304 PLL()->model->term->save_translations( reset( $arr ), $arr );
349 305 }
350 306
351 307 /**
352 - * Returns the post language.
308 + * Returns the post language
353 309 *
354 - * @api
355 310 * @since 1.5.4
356 311 *
357 - * @param int $post_id Post id.
358 - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'.
359 - * @return string|false The requested field for the post language, false if no language is associated to that post.
312 + * @param int $post_id
313 + * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
314 + * @return bool|string The requested field for the post language, false if no language is associated to that post
360 315 */
361 316 function pll_get_post_language( $post_id, $field = 'slug' ) {
362 317 return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
363 318 }
@@ -362,16 +317,15 @@
362 317 return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
363 318 }
364 319
365 320 /**
366 - * Returns the term language.
321 + * Returns the term language
367 322 *
368 - * @api
369 323 * @since 1.5.4
370 324 *
371 - * @param int $term_id Term id.
372 - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'.
373 - * @return string|false The requested field for the term language, false if no language is associated to that term.
325 + * @param int $term_id
326 + * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
327 + * @return bool|string The requested field for the term language, false if no language is associated to that term
374 328 */
375 329 function pll_get_term_language( $term_id, $field = 'slug' ) {
376 330 return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
377 331 }
@@ -376,15 +330,14 @@
376 330 return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
377 331 }
378 332
379 333 /**
380 - * Returns an array of translations of a post.
334 + * Returns an array of translations of a post
381 335 *
382 - * @api
383 336 * @since 1.8
384 337 *
385 - * @param int $post_id Post id.
386 - * @return int[] An associative array of translations with language code as key and translation post id as value.
338 + * @param int $post_id
339 + * @return array an associative array of translations with language code as key and translation post_id as value
387 340 */
388 341 function pll_get_post_translations( $post_id ) {
389 342 return PLL()->model->post->get_translations( $post_id );
390 343 }
@@ -389,15 +342,14 @@
389 342 return PLL()->model->post->get_translations( $post_id );
390 343 }
391 344
392 345 /**
393 - * Returns an array of translations of a term.
346 + * Returns an array of translations of a term
394 347 *
395 - * @api
396 348 * @since 1.8
397 349 *
398 - * @param int $term_id Term id.
399 - * @return int[] An associative array of translations with language code as key and translation term id as value.
350 + * @param int $term_id
351 + * @return array an associative array of translations with language code as key and translation term_id as value
400 352 */
401 353 function pll_get_term_translations( $term_id ) {
402 354 return PLL()->model->term->get_translations( $term_id );
403 355 }
@@ -402,29 +354,15 @@
402 354 return PLL()->model->term->get_translations( $term_id );
403 355 }
404 356
405 357 /**
406 - * Counts posts in a language.
358 + * Count posts in a language
407 359 *
408 - * @api
409 360 * @since 1.5
410 361 *
411 - * @param string $lang Language code.
412 - * @param array $args {
413 - * Optional arguments.
414 - * Accepted keys:
415 - *
416 - * @type string $post_type Post type.
417 - * @type int $m YearMonth ( ex: 201307 ).
418 - * @type int $year 4 digit year.
419 - * @type int $monthnum Month number (from 1 to 12).
420 - * @type int $day Day of the month (from 1 to 31).
421 - * @type int $author Author id.
422 - * @type string $author_name Author nicename.
423 - * @type string $post_format Post format.
424 - * @type string $post_status Post status.
425 - * }
426 - * @return int Posts count.
362 + * @param string $lang language code
363 + * @param array $args ( accepted keys: post_type, m, year, monthnum, day, author, author_name, post_format )
364 + * @return int posts count
427 365 */
428 366 function pll_count_posts( $lang, $args = array() ) {
429 367 return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
430 368 }
@@ -429,15 +367,13 @@
429 367 return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
430 368 }
431 369
432 370 /**
433 - * Allows to access the Polylang instance.
434 - * However, it is always preferable to use API functions
435 - * as internal methods may be changed without prior notice.
371 + * Allows to access the Polylang instance
372 + * It is always preferable to use API functions
373 + * Internal methods may be changed without prior notice
436 374 *
437 375 * @since 1.8
438 - *
439 - * @return PLL_Frontend|PLL_Admin|PLL_Settings|PLL_REST_Request
440 376 */
441 -function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
377 +function PLL() {
442 378 return $GLOBALS['polylang'];
443 379 }