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