PluginProbe
Polylang / 3.7.1
Polylang v3.7.1
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 +381 -135 2.9.1 → 3.7.1 View file →
@@ -1,117 +1,165 @@
1 1 <?php
2 2 /**
3 + * The Polylang public API.
4 + *
3 5 * @package Polylang
4 6 */
5 7
6 8 /**
7 - * Template tag: displays the language switcher
9 + * Template tag: displays the language switcher.
10 + * The function does nothing if used outside the frontend.
8 11 *
9 - * List of parameters accepted in $args:
10 - *
11 - * - dropdown => displays a dropdown if set to 1, defaults to 0
12 - * - echo => echoes the switcher if set to 1 ( default )
13 - * - hide_if_empty => hides languages with no posts ( or pages ) if set to 1 ( default )
14 - * - show_flags => shows flags if set to 1, defaults to 0
15 - * - show_names => shows languages names if set to 1 ( default )
16 - * - display_names_as => whether to display the language name or its slug, valid options are 'slug' and 'name',
17 - * defaults to name
18 - * - force_home => forces linking to the home page is set to 1, defaults to 0
19 - * - hide_if_no_translation => hides the link if there is no translation if set to 1, defaults to 0
20 - * - hide_current => hides the current language if set to 1, defaults to 0
21 - * - post_id => if not null, link to translations of post defined by post_id, defaults to null
22 - * - raw => set this to true to build your own custom language switcher, defaults to 0
23 - * - item_spacing => whether to preserve or discard whitespace between list items, valid options are
24 - * 'preserve' and 'discard', defaults to preserve
25 - *
26 12 * @api
27 13 * @since 0.5
28 14 *
29 - * @param array $args optional
30 - * @return null|string|array null if displaying, array if raw is requested, string otherwise
15 + * @param array $args {
16 + * Optional array of arguments.
17 + *
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.
31 32 */
32 -function pll_the_languages( $args = '' ) {
33 - if ( PLL() instanceof PLL_Frontend ) {
34 - $switcher = new PLL_Switcher();
35 - 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();
36 36 }
37 - return '';
37 +
38 + $switcher = new PLL_Switcher();
39 + return $switcher->the_languages( PLL()->links, $args );
38 40 }
39 41
40 42 /**
41 - * Returns the current language on frontend
42 - * 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).
43 45 *
44 46 * @api
45 47 * @since 0.8.1
48 + * @since 3.4 Accepts composite values.
46 49 *
47 - * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug', pass OBJECT constant to get the language object.
48 - * @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
49 61 */
50 62 function pll_current_language( $field = 'slug' ) {
51 - if ( OBJECT === $field ) {
63 + if ( empty( PLL()->curlang ) ) {
64 + return false;
65 + }
66 +
67 + if ( \OBJECT === $field ) {
52 68 return PLL()->curlang;
53 69 }
54 - return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false;
70 +
71 + return PLL()->curlang->get_prop( $field );
55 72 }
56 73
57 74 /**
58 - * Returns the default language
75 + * Returns the default language.
59 76 *
60 77 * @api
61 78 * @since 1.0
79 + * @since 3.4 Accepts composite values.
62 80 *
63 - * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug', pass OBJECT constant to get the language object.
64 - * @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
65 92 */
66 93 function pll_default_language( $field = 'slug' ) {
67 - if ( isset( PLL()->options['default_lang'] ) ) {
68 - $lang = PLL()->model->get_language( PLL()->options['default_lang'] );
69 - if ( $lang ) {
70 - if ( OBJECT === $field ) {
71 - return $lang;
72 - }
73 - return isset( $lang->$field ) ? $lang->$field : false;
74 - }
94 + $lang = PLL()->model->get_default_language();
95 +
96 + if ( empty( $lang ) ) {
97 + return false;
75 98 }
76 - return false;
99 +
100 + if ( \OBJECT === $field ) {
101 + return $lang;
102 + }
103 +
104 + return $lang->get_prop( $field );
77 105 }
78 106
79 107 /**
80 - * 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.
81 109 *
82 110 * @api
83 111 * @since 0.5
112 + * @since 3.4 Returns `0` instead of `false` if not translated or if the post has no language.
113 + * @since 3.4 $lang accepts `PLL_Language` or string.
84 114 *
85 - * @param int $post_id post id
86 - * @param string $slug optional language code, defaults to current language
87 - * @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 The translation post ID if exists. 0 if not translated, the post has no language or if the language doesn't exist.
118 + *
119 + * @phpstan-return int<0, max>
88 120 */
89 -function pll_get_post( $post_id, $slug = '' ) {
90 - 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 ?: pll_current_language();
123 +
124 + if ( empty( $lang ) ) {
125 + return 0;
126 + }
127 +
128 + return PLL()->model->post->get( $post_id, $lang );
91 129 }
92 130
93 131 /**
94 - * 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.
95 133 *
96 134 * @api
97 135 * @since 0.5
136 + * @since 3.4 Returns `0` instead of `false` if not translated or if the term has no language.
137 + * @since 3.4 $lang accepts PLL_Language or string.
98 138 *
99 - * @param int $term_id term id
100 - * @param string $slug optional language code, defaults to current language
101 - * @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 The translation term ID if exists. 0 if not translated, the term has no language or if the language doesn't exist.
142 + *
143 + * @phpstan-return int<0, max>
102 144 */
103 -function pll_get_term( $term_id, $slug = '' ) {
104 - return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->term->get( $term_id, $slug ) : null;
145 +function pll_get_term( $term_id, $lang = '' ) {
146 + $lang = $lang ?: pll_current_language();
147 +
148 + if ( empty( $lang ) ) {
149 + return 0;
150 + }
151 +
152 + return PLL()->model->term->get( $term_id, $lang );
105 153 }
106 154
107 155 /**
108 - * Returns the home url in the current language
156 + * Returns the home url in a language.
109 157 *
110 158 * @api
111 159 * @since 0.8
112 160 *
113 - * @param string $lang language code ( optional on frontend )
161 + * @param string $lang Optional language code, defaults to the current language.
114 162 * @return string
115 163 */
116 164 function pll_home_url( $lang = '' ) {
117 165 if ( empty( $lang ) ) {
@@ -117,21 +165,27 @@
117 165 if ( empty( $lang ) ) {
118 166 $lang = pll_current_language();
119 167 }
120 168
121 - 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 );
122 174 }
123 175
124 176 /**
125 - * Registers a string for translation in the "strings translation" panel
177 + * Registers a string for translation in the "strings translation" panel.
126 178 *
127 179 * @api
128 180 * @since 0.6
129 181 *
130 - * @param string $name a unique name for the string
131 - * @param string $string the string to register
132 - * @param string $context optional the group in which the string is registered, defaults to 'polylang'
133 - * @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
134 188 */
135 189 function pll_register_string( $name, $string, $context = 'Polylang', $multiline = false ) {
136 190 if ( PLL() instanceof PLL_Admin_Base ) {
137 191 PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
@@ -138,18 +192,22 @@
138 192 }
139 193 }
140 194
141 195 /**
142 - * Translates a string ( previously registered with pll_register_string )
196 + * Translates a string ( previously registered with pll_register_string ).
143 197 *
144 198 * @api
145 199 * @since 0.6
146 200 *
147 - * @param string $string the string to translate
148 - * @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.
149 203 */
150 204 function pll__( $string ) {
151 - 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
152 210 }
153 211
154 212 /**
155 213 * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
@@ -156,10 +214,10 @@
156 214 *
157 215 * @api
158 216 * @since 2.1
159 217 *
160 - * @param string $string the string to translate
161 - * @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.
162 220 */
163 221 function pll_esc_html__( $string ) {
164 222 return esc_html( pll__( $string ) );
165 223 }
@@ -169,10 +227,10 @@
169 227 *
170 228 * @api
171 229 * @since 2.1
172 230 *
173 - * @param string $string The string to translate
174 - * @return string
231 + * @param string $string The string to translate.
232 + * @return string The string translated in the current language.
175 233 */
176 234 function pll_esc_attr__( $string ) {
177 235 return esc_attr( pll__( $string ) );
178 236 }
@@ -183,9 +241,10 @@
183 241 *
184 242 * @api
185 243 * @since 0.6
186 244 *
187 - * @param string $string The string to translate
245 + * @param string $string The string to translate.
246 + * @return void
188 247 */
189 248 function pll_e( $string ) {
190 249 echo pll__( $string ); // phpcs:ignore
191 250 }
@@ -195,9 +254,10 @@
195 254 *
196 255 * @api
197 256 * @since 2.1
198 257 *
199 - * @param string $string The string to translate
258 + * @param string $string The string to translate.
259 + * @return void
200 260 */
201 261 function pll_esc_html_e( $string ) {
202 262 echo pll_esc_html__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
203 263 }
@@ -207,9 +267,10 @@
207 267 *
208 268 * @api
209 269 * @since 2.1
210 270 *
211 - * @param string $string The string to translate
271 + * @param string $string The string to translate.
272 + * @return void
212 273 */
213 274 function pll_esc_attr_e( $string ) {
214 275 echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
215 276 }
@@ -214,48 +275,45 @@
214 275 echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
215 276 }
216 277
217 278 /**
218 - * Translates a string ( previously registered with pll_register_string )
279 + * Translates a string ( previously registered with pll_register_string ).
219 280 *
220 281 * @api
221 282 * @since 1.5.4
222 283 *
223 - * @param string $string the string to translate
224 - * @param string $lang language code
225 - * @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.
226 287 */
227 288 function pll_translate_string( $string, $lang ) {
228 - if ( PLL() instanceof PLL_Frontend && pll_current_language() == $lang ) {
289 + if ( PLL() instanceof PLL_Frontend && pll_current_language() === $lang ) {
229 290 return pll__( $string );
230 291 }
231 292
232 - if ( ! is_scalar( $string ) ) {
293 + if ( ! is_scalar( $string ) || '' === $string ) {
233 294 return $string;
234 295 }
235 296
236 - static $cache; // Cache object to avoid loading the same translations object several times
297 + $lang = PLL()->model->get_language( $lang );
237 298
238 - if ( empty( $cache ) ) {
239 - $cache = new PLL_Cache();
299 + if ( empty( $lang ) ) {
300 + return $string;
240 301 }
241 302
242 - if ( false === $mo = $cache->get( $lang ) ) {
243 - $mo = new PLL_MO();
244 - $mo->import_from_db( PLL()->model->get_language( $lang ) );
245 - $cache->set( $lang, $mo );
246 - }
303 + $mo = new PLL_MO();
304 + $mo->import_from_db( $lang );
247 305
248 306 return $mo->translate( $string );
249 307 }
250 308
251 309 /**
252 - * Returns true if Polylang manages languages and translations for this post type
310 + * Returns true if Polylang manages languages and translations for this post type.
253 311 *
254 312 * @api
255 313 * @since 1.0.1
256 314 *
257 - * @param string $post_type Post type name
315 + * @param string $post_type Post type name.
258 316 * @return bool
259 317 */
260 318 function pll_is_translated_post_type( $post_type ) {
261 319 return PLL()->model->is_translated_post_type( $post_type );
@@ -261,14 +319,14 @@
261 319 return PLL()->model->is_translated_post_type( $post_type );
262 320 }
263 321
264 322 /**
265 - * Returns true if Polylang manages languages and translations for this taxonomy
323 + * Returns true if Polylang manages languages and translations for this taxonomy.
266 324 *
267 325 * @api
268 326 * @since 1.0.1
269 327 *
270 - * @param string $tax Taxonomy name
328 + * @param string $tax Taxonomy name.
271 329 * @return bool
272 330 */
273 331 function pll_is_translated_taxonomy( $tax ) {
274 332 return PLL()->model->is_translated_taxonomy( $tax );
@@ -274,20 +332,20 @@
274 332 return PLL()->model->is_translated_taxonomy( $tax );
275 333 }
276 334
277 335 /**
278 - * Returns the list of available languages
336 + * Returns the list of available languages.
279 337 *
280 - * List of parameters accepted in $args:
281 - *
282 - * hide_empty => hides languages with no posts if set to true ( defaults to false )
283 - * fields => return only that field if set ( see PLL_Language for a list of fields )
284 - *
285 338 * @api
286 339 * @since 1.5
287 340 *
288 - * @param array $args list of parameters
289 - * @return array
341 + * @param array $args {
342 + * Optional array of arguments.
343 + *
344 + * @type bool $hide_empty Hides languages with no posts if set to true ( defaults to false ).
345 + * @type string $fields Return only that field if set ( @see PLL_Language for a list of fields ), defaults to 'slug'.
346 + * }
347 + * @return string[]
290 348 */
291 349 function pll_languages_list( $args = array() ) {
292 350 $args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
293 351 return PLL()->model->get_languages_list( $args );
@@ -293,43 +351,60 @@
293 351 return PLL()->model->get_languages_list( $args );
294 352 }
295 353
296 354 /**
297 - * Set the post language
355 + * Sets the post language.
298 356 *
299 357 * @api
300 358 * @since 1.5
359 + * @since 3.4 $lang accepts PLL_Language or string.
360 + * @since 3.4 Returns a boolean.
301 361 *
302 - * @param int $id post id
303 - * @param string $lang language code
362 + * @param int $id Post ID.
363 + * @param PLL_Language|string $lang Language (object or slug).
364 + * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
365 + * the post).
304 366 */
305 367 function pll_set_post_language( $id, $lang ) {
306 - PLL()->model->post->set_language( $id, $lang );
368 + return PLL()->model->post->set_language( $id, $lang );
307 369 }
308 370
309 371 /**
310 - * Set the term language
372 + * Sets the term language.
311 373 *
312 374 * @api
313 375 * @since 1.5
376 + * @since 3.4 $lang accepts PLL_Language or string.
377 + * @since 3.4 Returns a boolean.
314 378 *
315 - * @param int $id term id
316 - * @param string $lang language code
379 + * @param int $id Term ID.
380 + * @param PLL_Language|string $lang Language (object or slug).
381 + * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
382 + * the term).
317 383 */
318 384 function pll_set_term_language( $id, $lang ) {
319 - PLL()->model->term->set_language( $id, $lang );
385 + return PLL()->model->term->set_language( $id, $lang );
320 386 }
321 387
322 388 /**
323 - * Save posts translations
389 + * Save posts translations.
324 390 *
325 391 * @api
326 392 * @since 1.5
393 + * @since 3.4 Returns an associative array of translations.
327 394 *
328 - * @param array $arr an associative array of translations with language code as key and post id as value
395 + * @param int[] $arr An associative array of translations with language code as key and post ID as value.
396 + * @return int[] An associative array with language codes as key and post IDs as values.
397 + *
398 + * @phpstan-return array<non-empty-string, positive-int>
329 399 */
330 400 function pll_save_post_translations( $arr ) {
331 - PLL()->model->post->save_translations( reset( $arr ), $arr );
401 + $id = reset( $arr );
402 + if ( $id ) {
403 + return PLL()->model->post->save_translations( $id, $arr );
404 + }
405 +
406 + return array();
332 407 }
333 408
334 409 /**
335 410 * Save terms translations
@@ -335,51 +410,94 @@
335 410 * Save terms translations
336 411 *
337 412 * @api
338 413 * @since 1.5
414 + * @since 3.4 Returns an associative array of translations.
339 415 *
340 - * @param array $arr an associative array of translations with language code as key and term id as value
416 + * @param int[] $arr An associative array of translations with language code as key and term ID as value.
417 + * @return int[] An associative array with language codes as key and term IDs as values.
418 + *
419 + * @phpstan-return array<non-empty-string, positive-int>
341 420 */
342 421 function pll_save_term_translations( $arr ) {
343 - PLL()->model->term->save_translations( reset( $arr ), $arr );
422 + $id = reset( $arr );
423 + if ( $id ) {
424 + return PLL()->model->term->save_translations( $id, $arr );
425 + }
426 +
427 + return array();
344 428 }
345 429
346 430 /**
347 - * Returns the post language
431 + * Returns the post language.
348 432 *
349 433 * @api
350 434 * @since 1.5.4
435 + * @since 3.4 Accepts composite values for `$field`.
351 436 *
352 - * @param int $post_id
353 - * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
354 - * @return bool|string The requested field for the post language, false if no language is associated to that post
437 + * @param int $post_id Post ID.
438 + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
439 + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language
440 + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
441 + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
442 + * @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.
443 + *
444 + * @phpstan-return (
445 + * $field is \OBJECT ? PLL_Language : (
446 + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
447 + * )
448 + * )|false
355 449 */
356 450 function pll_get_post_language( $post_id, $field = 'slug' ) {
357 - return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
451 + $lang = PLL()->model->post->get_language( $post_id );
452 +
453 + if ( empty( $lang ) || \OBJECT === $field ) {
454 + return $lang;
455 + }
456 +
457 + return $lang->get_prop( $field );
358 458 }
359 459
360 460 /**
361 - * Returns the term language
461 + * Returns the term language.
362 462 *
363 463 * @api
364 464 * @since 1.5.4
465 + * @since 3.4 Accepts composite values for `$field`.
365 466 *
366 - * @param int $term_id
367 - * @param string $field Optional, the language field to return ( see PLL_Language ), defaults to 'slug'
368 - * @return bool|string The requested field for the term language, false if no language is associated to that term
467 + * @param int $term_id Term ID.
468 + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
469 + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language
470 + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
471 + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
472 + * @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.
473 + *
474 + * @phpstan-return (
475 + * $field is \OBJECT ? PLL_Language : (
476 + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
477 + * )
478 + * )|false
369 479 */
370 480 function pll_get_term_language( $term_id, $field = 'slug' ) {
371 - return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
481 + $lang = PLL()->model->term->get_language( $term_id );
482 +
483 + if ( empty( $lang ) || \OBJECT === $field ) {
484 + return $lang;
485 + }
486 +
487 + return $lang->get_prop( $field );
372 488 }
373 489
374 490 /**
375 - * Returns an array of translations of a post
491 + * Returns an array of translations of a post.
376 492 *
377 493 * @api
378 494 * @since 1.8
379 495 *
380 - * @param int $post_id
381 - * @return array an associative array of translations with language code as key and translation post_id as value
496 + * @param int $post_id Post ID.
497 + * @return int[] An associative array of translations with language code as key and translation post ID as value.
498 + *
499 + * @phpstan-return array<non-empty-string, positive-int>
382 500 */
383 501 function pll_get_post_translations( $post_id ) {
384 502 return PLL()->model->post->get_translations( $post_id );
385 503 }
@@ -384,15 +502,17 @@
384 502 return PLL()->model->post->get_translations( $post_id );
385 503 }
386 504
387 505 /**
388 - * Returns an array of translations of a term
506 + * Returns an array of translations of a term.
389 507 *
390 508 * @api
391 509 * @since 1.8
392 510 *
393 - * @param int $term_id
394 - * @return array an associative array of translations with language code as key and translation term_id as value
511 + * @param int $term_id Term ID.
512 + * @return int[] An associative array of translations with language code as key and translation term ID as value.
513 + *
514 + * @phpstan-return array<non-empty-string, positive-int>
395 515 */
396 516 function pll_get_term_translations( $term_id ) {
397 517 return PLL()->model->term->get_translations( $term_id );
398 518 }
@@ -397,27 +517,153 @@
397 517 return PLL()->model->term->get_translations( $term_id );
398 518 }
399 519
400 520 /**
401 - * Count posts in a language
521 + * Counts posts in a language.
402 522 *
403 523 * @api
404 524 * @since 1.5
405 525 *
406 526 * @param string $lang Language code.
407 - * @param array $args WP_Query arguments ( accepted keys: post_type, m, year, monthnum, day, author, author_name, post_format, post_status ).
527 + * @param array $args {
528 + * Optional array of arguments.
529 + *
530 + * @type string $post_type Post type.
531 + * @type int $m YearMonth ( ex: 201307 ).
532 + * @type int $year 4 digit year.
533 + * @type int $monthnum Month number (from 1 to 12).
534 + * @type int $day Day of the month (from 1 to 31).
535 + * @type int $author Author id.
536 + * @type string $author_name Author nicename.
537 + * @type string $post_format Post format.
538 + * @type string $post_status Post status.
539 + * }
408 540 * @return int Posts count.
409 541 */
410 542 function pll_count_posts( $lang, $args = array() ) {
411 - return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
543 + $lang = PLL()->model->get_language( $lang );
544 +
545 + if ( empty( $lang ) ) {
546 + return 0;
547 + }
548 +
549 + return PLL()->model->count_posts( $lang, $args );
412 550 }
413 551
414 552 /**
415 - * Allows to access the Polylang instance
416 - * It is always preferable to use API functions
417 - * Internal methods may be changed without prior notice
553 + * Wraps `wp_insert_post` with language feature.
418 554 *
555 + * @since 3.7
556 + *
557 + * @param array $postarr {
558 + * An array of elements that make up a post to insert.
559 + * @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments.
560 + *
561 + * @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values.
562 + * }
563 + * @param PLL_Language|string $language The post language object or slug.
564 + * @return int|WP_Error The post ID on success. The value `WP_Error` on failure.
565 + */
566 +function pll_insert_post( array $postarr, $language ) {
567 + $language = PLL()->model->get_language( $language );
568 +
569 + if ( ! $language instanceof PLL_Language ) {
570 + return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) );
571 + }
572 +
573 + return PLL()->model->post->insert( $postarr, $language );
574 +}
575 +
576 +/**
577 + * Wraps `wp_insert_term` with language feature.
578 + *
579 + * @since 3.7
580 + *
581 + * @param string $term The term name to add.
582 + * @param string $taxonomy The taxonomy to which to add the term.
583 + * @param PLL_Language|string $language The term language object or slug.
584 + * @param array $args {
585 + * Optional. Array of arguments for inserting a term.
586 + *
587 + * @type string $alias_of Slug of the term to make this term an alias of.
588 + * Default empty string. Accepts a term slug.
589 + * @type string $description The term description. Default empty string.
590 + * @type int $parent The id of the parent term. Default 0.
591 + * @type string $slug The term slug to use. Default empty string.
592 + * @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values.
593 + * }
594 + * @return array|WP_Error {
595 + * An array of the new term data, `WP_Error` otherwise.
596 + *
597 + * @type int $term_id The new term ID.
598 + * @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
599 + * }
600 + */
601 +function pll_insert_term( string $term, string $taxonomy, $language, array $args = array() ) {
602 + $language = PLL()->model->get_language( $language );
603 +
604 + if ( ! $language instanceof PLL_Language ) {
605 + return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) );
606 + }
607 +
608 + return PLL()->model->term->insert( $term, $taxonomy, $language, $args );
609 +}
610 +
611 +/**
612 + * Wraps `wp_update_post` with language feature.
613 + *
614 + * @since 3.7
615 + *
616 + * @param array $postarr {
617 + * Optional. An array of elements that make up a post to update.
618 + * @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments.
619 + *
620 + * @type PLL_Language|string $lang The post language object or slug.
621 + * @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values.
622 + * }
623 + * @return int|WP_Error The post ID on success. The value `WP_Error` on failure.
624 + */
625 +function pll_update_post( array $postarr ) {
626 + return PLL()->model->post->update( $postarr );
627 +}
628 +
629 +/**
630 + * Wraps `wp_update_term` with language feature.
631 + *
632 + * @since 3.7
633 + *
634 + * @param int $term_id The ID of the term.
635 + * @param array $args {
636 + * Optional. Array of arguments for updating a term.
637 + *
638 + * @type string $alias_of Slug of the term to make this term an alias of.
639 + * Default empty string. Accepts a term slug.
640 + * @type string $description The term description. Default empty string.
641 + * @type int $parent The id of the parent term. Default 0.
642 + * @type string $slug The term slug to use. Default empty string.
643 + * @type string $name The term name.
644 + * @type PLL_Language|string $lang The term language object or slug.
645 + * @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values.
646 + * }
647 + * @return array|WP_Error {
648 + * An array containing the `term_id` and `term_taxonomy_id`, `WP_Error` otherwise.
649 + *
650 + * @type int $term_id The new term ID.
651 + * @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
652 + * }
653 + */
654 +function pll_update_term( int $term_id, array $args = array() ) {
655 + return PLL()->model->term->update( $term_id, $args );
656 +}
657 +
658 +/**
659 + * Allows to access the Polylang instance.
660 + * However, it is always preferable to use API functions
661 + * as internal methods may be changed without prior notice.
662 + *
419 663 * @since 1.8
664 + *
665 + * @return PLL_Frontend|PLL_Admin|PLL_Settings|PLL_REST_Request
420 666 */
421 667 function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
422 668 return $GLOBALS['polylang'];
423 669 }