← All changes | include/api.php +411 -134 2.7.2 → 3.7.1 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` if not translated or if the post has no language.
	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 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>
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 ?: pll_current_language();
	123	+
	124	+ if ( empty( $lang ) ) {
	125	+ return 0;
	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` if not translated or if the term has no language.
	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 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>
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 = '' ) {
	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 );
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,46 +275,45 @@
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
219		- if ( empty( $cache ) ) {
220		- $cache = new PLL_Cache();
	299	+ if ( empty( $lang ) ) {
	300	+ return $string;
221	301	}
222	302
223		- if ( false === $mo = $cache->get( $lang ) ) {
224		- $mo = new PLL_MO();
225		- $mo->import_from_db( PLL()->model->get_language( $lang ) );
226		- $cache->set( $lang, $mo );
227		- }
	303	+ $mo = new PLL_MO();
	304	+ $mo->import_from_db( $lang );
228	305
229	306	return $mo->translate( $string );
230	307	}
231	308
232	309	/**
233		- * 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.
234	311	*
	312	+ * @api
235	313	* @since 1.0.1
236	314	*
237		- * @param string $post_type Post type name
	315	+ * @param string $post_type Post type name.
238	316	* @return bool
239	317	*/
240	318	function pll_is_translated_post_type( $post_type ) {
241	319	return PLL()->model->is_translated_post_type( $post_type );
		@@ -241,13 +319,14 @@
241	319	return PLL()->model->is_translated_post_type( $post_type );
242	320	}
243	321
244	322	/**
245		- * Returns true if Polylang manages languages and translations for this taxonomy
	323	+ * Returns true if Polylang manages languages and translations for this taxonomy.
246	324	*
	325	+ * @api
247	326	* @since 1.0.1
248	327	*
249		- * @param string $tax Taxonomy name
	328	+ * @param string $tax Taxonomy name.
250	329	* @return bool
251	330	*/
252	331	function pll_is_translated_taxonomy( $tax ) {
253	332	return PLL()->model->is_translated_taxonomy( $tax );
		@@ -253,19 +332,20 @@
253	332	return PLL()->model->is_translated_taxonomy( $tax );
254	333	}
255	334
256	335	/**
257		- * Returns the list of available languages
	336	+ * Returns the list of available languages.
258	337	*
259		- * List of parameters accepted in $args:
	338	+ * @api
	339	+ * @since 1.5
260	340	*
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 )
	341	+ * @param array $args {
	342	+ * Optional array of arguments.
263	343	*
264		- * @since 1.5
265		- *
266		- * @param array $args list of parameters
267		- * @return array
	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[]
268	348	*/
269	349	function pll_languages_list( $args = array() ) {
270	350	$args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
271	351	return PLL()->model->get_languages_list( $args );
		@@ -271,86 +351,153 @@
271	351	return PLL()->model->get_languages_list( $args );
272	352	}
273	353
274	354	/**
275		- * Set the post language
	355	+ * Sets the post language.
276	356	*
	357	+ * @api
277	358	* @since 1.5
	359	+ * @since 3.4 $lang accepts PLL_Language or string.
	360	+ * @since 3.4 Returns a boolean.
278	361	*
279		- * @param int $id post id
280		- * @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).
281	366	*/
282	367	function pll_set_post_language( $id, $lang ) {
283		- PLL()->model->post->set_language( $id, $lang );
	368	+ return PLL()->model->post->set_language( $id, $lang );
284	369	}
285	370
286	371	/**
287		- * Set the term language
	372	+ * Sets the term language.
288	373	*
	374	+ * @api
289	375	* @since 1.5
	376	+ * @since 3.4 $lang accepts PLL_Language or string.
	377	+ * @since 3.4 Returns a boolean.
290	378	*
291		- * @param int $id term id
292		- * @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).
293	383	*/
294	384	function pll_set_term_language( $id, $lang ) {
295		- PLL()->model->term->set_language( $id, $lang );
	385	+ return PLL()->model->term->set_language( $id, $lang );
296	386	}
297	387
298	388	/**
299		- * Save posts translations
	389	+ * Save posts translations.
300	390	*
	391	+ * @api
301	392	* @since 1.5
	393	+ * @since 3.4 Returns an associative array of translations.
302	394	*
303		- * @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>
304	399	*/
305	400	function pll_save_post_translations( $arr ) {
306		- 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();
307	407	}
308	408
309	409	/**
310	410	* Save terms translations
311	411	*
	412	+ * @api
312	413	* @since 1.5
	414	+ * @since 3.4 Returns an associative array of translations.
313	415	*
314		- * @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>
315	420	*/
316	421	function pll_save_term_translations( $arr ) {
317		- 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();
318	428	}
319	429
320	430	/**
321		- * Returns the post language
	431	+ * Returns the post language.
322	432	*
	433	+ * @api
323	434	* @since 1.5.4
	435	+ * @since 3.4 Accepts composite values for `$field`.
324	436	*
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
	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
328	449	*/
329	450	function pll_get_post_language( $post_id, $field = 'slug' ) {
330		- 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 );
331	458	}
332	459
333	460	/**
334		- * Returns the term language
	461	+ * Returns the term language.
335	462	*
	463	+ * @api
336	464	* @since 1.5.4
	465	+ * @since 3.4 Accepts composite values for `$field`.
337	466	*
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
	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
341	479	*/
342	480	function pll_get_term_language( $term_id, $field = 'slug' ) {
343		- 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 );
344	488	}
345	489
346	490	/**
347		- * Returns an array of translations of a post
	491	+ * Returns an array of translations of a post.
348	492	*
	493	+ * @api
349	494	* @since 1.8
350	495	*
351		- * @param int $post_id
352		- * @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>
353	500	*/
354	501	function pll_get_post_translations( $post_id ) {
355	502	return PLL()->model->post->get_translations( $post_id );
356	503	}
		@@ -355,14 +502,17 @@
355	502	return PLL()->model->post->get_translations( $post_id );
356	503	}
357	504
358	505	/**
359		- * Returns an array of translations of a term
	506	+ * Returns an array of translations of a term.
360	507	*
	508	+ * @api
361	509	* @since 1.8
362	510	*
363		- * @param int $term_id
364		- * @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>
365	515	*/
366	516	function pll_get_term_translations( $term_id ) {
367	517	return PLL()->model->term->get_translations( $term_id );
368	518	}
		@@ -367,26 +517,153 @@
367	517	return PLL()->model->term->get_translations( $term_id );
368	518	}
369	519
370	520	/**
371		- * Count posts in a language
	521	+ * Counts posts in a language.
372	522	*
	523	+ * @api
373	524	* @since 1.5
374	525	*
375	526	* @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 ).
	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	+ * }
377	540	* @return int Posts count.
378	541	*/
379	542	function pll_count_posts( $lang, $args = array() ) {
380		- 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 );
381	550	}
382	551
383	552	/**
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
	553	+ * Wraps `wp_insert_post` with language feature.
387	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	+ *
388	663	* @since 1.8
	664	+ *
	665	+ * @return PLL_Frontend|PLL_Admin|PLL_Settings|PLL_REST_Request
389	666	*/
390	667	function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
391	668	return $GLOBALS['polylang'];
392	669	}