api.php: 3.1 vs 2.7 · Polylang

← All changes | include/api.php +157 -106 2.7 → 3.1 View file →

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