PluginProbe
Polylang / 3.6.7
Polylang v3.6.7
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 +194 -63 3.0.3 → 3.6.7 View file →
@@ -1,6 +1,8 @@
1 1 <?php
2 2 /**
3 + * The Polylang public API.
4 + *
3 5 * @package Polylang
4 6 */
5 7
6 8 /**
@@ -28,8 +30,12 @@
28 30 * }
29 31 * @return string|array Either the html markup of the switcher or the raw elements to build a custom language switcher.
30 32 */
31 33 function pll_the_languages( $args = array() ) {
34 + if ( empty( PLL()->links ) ) {
35 + return empty( $args['raw'] ) ? '' : array();
36 + }
37 +
32 38 $switcher = new PLL_Switcher();
33 39 return $switcher->the_languages( PLL()->links, $args );
34 40 }
35 41
@@ -34,21 +40,36 @@
34 40 }
35 41
36 42 /**
37 43 * Returns the current language on frontend.
38 - * Returns the language set in admin language filter on backend ( false if set to all languages ).
44 + * Returns the language set in admin language filter on backend (false if set to all languages).
39 45 *
40 46 * @api
41 47 * @since 0.8.1
48 + * @since 3.4 Accepts composite values.
42 49 *
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.
50 + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
51 + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language
52 + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
53 + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
54 + * @return string|int|bool|string[]|PLL_Language The requested field or object for the current language, `false` if the field isn't set or if current language doesn't exist yet.
55 + *
56 + * @phpstan-return (
57 + * $field is \OBJECT ? PLL_Language : (
58 + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
59 + * )
60 + * )|false
45 61 */
46 62 function pll_current_language( $field = 'slug' ) {
47 - if ( OBJECT === $field ) {
63 + if ( empty( PLL()->curlang ) ) {
64 + return false;
65 + }
66 +
67 + if ( \OBJECT === $field ) {
48 68 return PLL()->curlang;
49 69 }
50 - return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false;
70 +
71 + return PLL()->curlang->get_prop( $field );
51 72 }
52 73
53 74 /**
54 75 * Returns the default language.
@@ -54,51 +75,82 @@
54 75 * Returns the default language.
55 76 *
56 77 * @api
57 78 * @since 1.0
79 + * @since 3.4 Accepts composite values.
58 80 *
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.
81 + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
82 + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language
83 + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
84 + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
85 + * @return string|int|bool|string[]|PLL_Language The requested field or object for the default language, `false` if the field isn't set or if default language doesn't exist yet.
86 + *
87 + * @phpstan-return (
88 + * $field is \OBJECT ? PLL_Language : (
89 + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
90 + * )
91 + * )|false
61 92 */
62 93 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 - }
94 + $lang = PLL()->model->get_default_language();
95 +
96 + if ( empty( $lang ) ) {
97 + return false;
71 98 }
72 - return false;
99 +
100 + if ( \OBJECT === $field ) {
101 + return $lang;
102 + }
103 +
104 + return $lang->get_prop( $field );
73 105 }
74 106
75 107 /**
76 - * Among the post and its translations, returns the id of the post which is in the language represented by $lang.
108 + * Among the post and its translations, returns the ID of the post which is in the language represented by $lang.
77 109 *
78 110 * @api
79 111 * @since 0.5
112 + * @since 3.4 Returns 0 instead of false.
113 + * @since 3.4 $lang accepts PLL_Language or string.
80 114 *
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.
115 + * @param int $post_id Post ID.
116 + * @param PLL_Language|string $lang Optional language (object or slug), defaults to the current language.
117 + * @return int|false The translation post ID if exists, otherwise the passed ID. False if the passed object has no language or if the language doesn't exist.
118 + *
119 + * @phpstan-return int<0, max>|false
84 120 */
85 121 function pll_get_post( $post_id, $lang = '' ) {
86 - return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->post->get( $post_id, $lang ) : null;
122 + $lang = $lang ? $lang : pll_current_language();
123 +
124 + if ( empty( $lang ) ) {
125 + return false;
126 + }
127 +
128 + return PLL()->model->post->get( $post_id, $lang );
87 129 }
88 130
89 131 /**
90 - * Among the term and its translations, returns the id of the term which is in the language represented by $lang.
132 + * Among the term and its translations, returns the ID of the term which is in the language represented by $lang.
91 133 *
92 134 * @api
93 135 * @since 0.5
136 + * @since 3.4 Returns 0 instead of false.
137 + * @since 3.4 $lang accepts PLL_Language or string.
94 138 *
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.
139 + * @param int $term_id Term ID.
140 + * @param PLL_Language|string $lang Optional language (object or slug), defaults to the current language.
141 + * @return int|false The translation term ID if exists, otherwise the passed ID. False if the passed object has no language or if the language doesn't exist.
142 + *
143 + * @phpstan-return int<0, max>|false
98 144 */
99 -function pll_get_term( $term_id, $lang = '' ) {
100 - return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->term->get( $term_id, $lang ) : null;
145 +function pll_get_term( $term_id, $lang = null ) {
146 + $lang = $lang ? $lang : pll_current_language();
147 +
148 + if ( empty( $lang ) ) {
149 + return false;
150 + }
151 +
152 + return PLL()->model->term->get( $term_id, $lang );
101 153 }
102 154
103 155 /**
104 156 * Returns the home url in a language.
@@ -113,9 +165,13 @@
113 165 if ( empty( $lang ) ) {
114 166 $lang = pll_current_language();
115 167 }
116 168
117 - return empty( $lang ) ? home_url( '/' ) : PLL()->links->get_home_url( $lang );
169 + if ( empty( $lang ) || empty( PLL()->links ) ) {
170 + return home_url( '/' );
171 + }
172 +
173 + return PLL()->links->get_home_url( $lang );
118 174 }
119 175
120 176 /**
121 177 * Registers a string for translation in the "strings translation" panel.
@@ -145,9 +201,13 @@
145 201 * @param string $string The string to translate.
146 202 * @return string The string translated in the current language.
147 203 */
148 204 function pll__( $string ) {
149 - return is_scalar( $string ) ? __( $string, 'pll_string' ) : $string; // PHPCS:ignore WordPress.WP.I18n
205 + if ( ! is_scalar( $string ) || '' === $string ) {
206 + return $string;
207 + }
208 +
209 + return __( $string, 'pll_string' ); // PHPCS:ignore WordPress.WP.I18n
150 210 }
151 211
152 212 /**
153 213 * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
@@ -225,16 +285,22 @@
225 285 * @param string $lang Language code.
226 286 * @return string The string translated in the requested language.
227 287 */
228 288 function pll_translate_string( $string, $lang ) {
229 - if ( PLL() instanceof PLL_Frontend && pll_current_language() == $lang ) {
289 + if ( PLL() instanceof PLL_Frontend && pll_current_language() === $lang ) {
230 290 return pll__( $string );
231 291 }
232 292
233 - if ( ! is_scalar( $string ) ) {
293 + if ( ! is_scalar( $string ) || '' === $string ) {
234 294 return $string;
235 295 }
236 296
297 + $lang = PLL()->model->get_language( $lang );
298 +
299 + if ( empty( $lang ) ) {
300 + return $string;
301 + }
302 +
237 303 static $cache; // Cache object to avoid loading the same translations object several times.
238 304
239 305 if ( empty( $cache ) ) {
240 306 $cache = new PLL_Cache();
@@ -239,12 +305,14 @@
239 305 if ( empty( $cache ) ) {
240 306 $cache = new PLL_Cache();
241 307 }
242 308
243 - if ( false === $mo = $cache->get( $lang ) ) {
309 + $mo = $cache->get( $lang->slug );
310 +
311 + if ( ! $mo instanceof PLL_MO ) {
244 312 $mo = new PLL_MO();
245 - $mo->import_from_db( PLL()->model->get_language( $lang ) );
246 - $cache->set( $lang, $mo );
313 + $mo->import_from_db( $lang );
314 + $cache->set( $lang->slug, $mo );
247 315 }
248 316
249 317 return $mo->translate( $string );
250 318 }
@@ -298,15 +366,18 @@
298 366 * Sets the post language.
299 367 *
300 368 * @api
301 369 * @since 1.5
370 + * @since 3.4 $lang accepts PLL_Language or string.
371 + * @since 3.4 Returns a boolean.
302 372 *
303 - * @param int $id Post id.
304 - * @param string $lang Language code.
305 - * @return void
373 + * @param int $id Post ID.
374 + * @param PLL_Language|string $lang Language (object or slug).
375 + * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
376 + * the post).
306 377 */
307 378 function pll_set_post_language( $id, $lang ) {
308 - PLL()->model->post->set_language( $id, $lang );
379 + return PLL()->model->post->set_language( $id, $lang );
309 380 }
310 381
311 382 /**
312 383 * Sets the term language.
@@ -312,15 +383,18 @@
312 383 * Sets the term language.
313 384 *
314 385 * @api
315 386 * @since 1.5
387 + * @since 3.4 $lang accepts PLL_Language or string.
388 + * @since 3.4 Returns a boolean.
316 389 *
317 - * @param int $id Term id.
318 - * @param string $lang Language code.
319 - * @return void
390 + * @param int $id Term ID.
391 + * @param PLL_Language|string $lang Language (object or slug).
392 + * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
393 + * the term).
320 394 */
321 395 function pll_set_term_language( $id, $lang ) {
322 - PLL()->model->term->set_language( $id, $lang );
396 + return PLL()->model->term->set_language( $id, $lang );
323 397 }
324 398
325 399 /**
326 400 * Save posts translations.
@@ -326,14 +400,22 @@
326 400 * Save posts translations.
327 401 *
328 402 * @api
329 403 * @since 1.5
404 + * @since 3.4 Returns an associative array of translations.
330 405 *
331 - * @param int[] $arr An associative array of translations with language code as key and post id as value.
332 - * @return void
406 + * @param int[] $arr An associative array of translations with language code as key and post ID as value.
407 + * @return int[] An associative array with language codes as key and post IDs as values.
408 + *
409 + * @phpstan-return array<non-empty-string, positive-int>
333 410 */
334 411 function pll_save_post_translations( $arr ) {
335 - PLL()->model->post->save_translations( reset( $arr ), $arr );
412 + $id = reset( $arr );
413 + if ( $id ) {
414 + return PLL()->model->post->save_translations( $id, $arr );
415 + }
416 +
417 + return array();
336 418 }
337 419
338 420 /**
339 421 * Save terms translations
@@ -339,14 +421,22 @@
339 421 * Save terms translations
340 422 *
341 423 * @api
342 424 * @since 1.5
425 + * @since 3.4 Returns an associative array of translations.
343 426 *
344 - * @param int[] $arr An associative array of translations with language code as key and term id as value.
345 - * @return void
427 + * @param int[] $arr An associative array of translations with language code as key and term ID as value.
428 + * @return int[] An associative array with language codes as key and term IDs as values.
429 + *
430 + * @phpstan-return array<non-empty-string, positive-int>
346 431 */
347 432 function pll_save_term_translations( $arr ) {
348 - PLL()->model->term->save_translations( reset( $arr ), $arr );
433 + $id = reset( $arr );
434 + if ( $id ) {
435 + return PLL()->model->term->save_translations( $id, $arr );
436 + }
437 +
438 + return array();
349 439 }
350 440
351 441 /**
352 442 * Returns the post language.
@@ -352,15 +442,31 @@
352 442 * Returns the post language.
353 443 *
354 444 * @api
355 445 * @since 1.5.4
446 + * @since 3.4 Accepts composite values for `$field`.
356 447 *
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.
448 + * @param int $post_id Post ID.
449 + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
450 + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language
451 + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
452 + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
453 + * @return string|int|bool|string[]|PLL_Language The requested field or object for the post language, `false` if no language is associated to that post.
454 + *
455 + * @phpstan-return (
456 + * $field is \OBJECT ? PLL_Language : (
457 + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
458 + * )
459 + * )|false
360 460 */
361 461 function pll_get_post_language( $post_id, $field = 'slug' ) {
362 - return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
462 + $lang = PLL()->model->post->get_language( $post_id );
463 +
464 + if ( empty( $lang ) || \OBJECT === $field ) {
465 + return $lang;
466 + }
467 +
468 + return $lang->get_prop( $field );
363 469 }
364 470
365 471 /**
366 472 * Returns the term language.
@@ -366,15 +472,31 @@
366 472 * Returns the term language.
367 473 *
368 474 * @api
369 475 * @since 1.5.4
476 + * @since 3.4 Accepts composite values for `$field`.
370 477 *
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.
478 + * @param int $term_id Term ID.
479 + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
480 + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language
481 + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
482 + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
483 + * @return string|int|bool|string[]|PLL_Language The requested field or object for the post language, `false` if no language is associated to that term.
484 + *
485 + * @phpstan-return (
486 + * $field is \OBJECT ? PLL_Language : (
487 + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
488 + * )
489 + * )|false
374 490 */
375 491 function pll_get_term_language( $term_id, $field = 'slug' ) {
376 - return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
492 + $lang = PLL()->model->term->get_language( $term_id );
493 +
494 + if ( empty( $lang ) || \OBJECT === $field ) {
495 + return $lang;
496 + }
497 +
498 + return $lang->get_prop( $field );
377 499 }
378 500
379 501 /**
380 502 * Returns an array of translations of a post.
@@ -381,10 +503,12 @@
381 503 *
382 504 * @api
383 505 * @since 1.8
384 506 *
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.
507 + * @param int $post_id Post ID.
508 + * @return int[] An associative array of translations with language code as key and translation post ID as value.
509 + *
510 + * @phpstan-return array<non-empty-string, positive-int>
387 511 */
388 512 function pll_get_post_translations( $post_id ) {
389 513 return PLL()->model->post->get_translations( $post_id );
390 514 }
@@ -394,10 +518,12 @@
394 518 *
395 519 * @api
396 520 * @since 1.8
397 521 *
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.
522 + * @param int $term_id Term ID.
523 + * @return int[] An associative array of translations with language code as key and translation term ID as value.
524 + *
525 + * @phpstan-return array<non-empty-string, positive-int>
400 526 */
401 527 function pll_get_term_translations( $term_id ) {
402 528 return PLL()->model->term->get_translations( $term_id );
403 529 }
@@ -409,10 +535,9 @@
409 535 * @since 1.5
410 536 *
411 537 * @param string $lang Language code.
412 538 * @param array $args {
413 - * Optional arguments.
414 - * Accepted keys:
539 + * Optional array of arguments.
415 540 *
416 541 * @type string $post_type Post type.
417 542 * @type int $m YearMonth ( ex: 201307 ).
418 543 * @type int $year 4 digit year.
@@ -425,9 +550,15 @@
425 550 * }
426 551 * @return int Posts count.
427 552 */
428 553 function pll_count_posts( $lang, $args = array() ) {
429 - return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
554 + $lang = PLL()->model->get_language( $lang );
555 +
556 + if ( empty( $lang ) ) {
557 + return 0;
558 + }
559 +
560 + return PLL()->model->count_posts( $lang, $args );
430 561 }
431 562
432 563 /**
433 564 * Allows to access the Polylang instance.