polylang / include / api.php

api.php in Polylang 3.6.5, at include/api.php

575 lines 17.3 KB

Raw Download Zip

1	<?php
2	/**
3	* The Polylang public API.
4	*
5	* @package Polylang
6	*/
7
8	/**
9	* Template tag: displays the language switcher.
10	* The function does nothing if used outside the frontend.
11	*
12	* @api
13	* @since 0.5
14	*
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.
32	*/
33	function pll_the_languages( $args = array() ) {
34	if ( empty( PLL()->links ) ) {
35	return empty( $args['raw'] ) ? '' : array();
36	}
37
38	$switcher = new PLL_Switcher();
39	return $switcher->the_languages( PLL()->links, $args );
40	}
41
42	/**
43	* Returns the current language on frontend.
44	* Returns the language set in admin language filter on backend (false if set to all languages).
45	*
46	* @api
47	* @since 0.8.1
48	* @since 3.4 Accepts composite values.
49	*
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
61	*/
62	function pll_current_language( $field = 'slug' ) {
63	if ( empty( PLL()->curlang ) ) {
64	return false;
65	}
66
67	if ( \OBJECT === $field ) {
68	return PLL()->curlang;
69	}
70
71	return PLL()->curlang->get_prop( $field );
72	}
73
74	/**
75	* Returns the default language.
76	*
77	* @api
78	* @since 1.0
79	* @since 3.4 Accepts composite values.
80	*
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
92	*/
93	function pll_default_language( $field = 'slug' ) {
94	$lang = PLL()->model->get_default_language();
95
96	if ( empty( $lang ) ) {
97	return false;
98	}
99
100	if ( \OBJECT === $field ) {
101	return $lang;
102	}
103
104	return $lang->get_prop( $field );
105	}
106
107	/**
108	* Among the post and its translations, returns the ID of the post which is in the language represented by $lang.
109	*
110	* @api
111	* @since 0.5
112	* @since 3.4 Returns 0 instead of false.
113	* @since 3.4 $lang accepts PLL_Language or string.
114	*
115	* @param int $post_id Post ID.
116	* @param PLL_Language\|string $lang Optional language (object or slug), defaults to the current language.
117	* @return int\|false The translation post ID if exists, otherwise the passed ID. False if the passed object has no language or if the language doesn't exist.
118	*
119	* @phpstan-return int<0, max>\|false
120	*/
121	function pll_get_post( $post_id, $lang = '' ) {
122	$lang = $lang ? $lang : pll_current_language();
123
124	if ( empty( $lang ) ) {
125	return false;
126	}
127
128	return PLL()->model->post->get( $post_id, $lang );
129	}
130
131	/**
132	* Among the term and its translations, returns the ID of the term which is in the language represented by $lang.
133	*
134	* @api
135	* @since 0.5
136	* @since 3.4 Returns 0 instead of false.
137	* @since 3.4 $lang accepts PLL_Language or string.
138	*
139	* @param int $term_id Term ID.
140	* @param PLL_Language\|string $lang Optional language (object or slug), defaults to the current language.
141	* @return int\|false The translation term ID if exists, otherwise the passed ID. False if the passed object has no language or if the language doesn't exist.
142	*
143	* @phpstan-return int<0, max>\|false
144	*/
145	function pll_get_term( $term_id, $lang = null ) {
146	$lang = $lang ? $lang : pll_current_language();
147
148	if ( empty( $lang ) ) {
149	return false;
150	}
151
152	return PLL()->model->term->get( $term_id, $lang );
153	}
154
155	/**
156	* Returns the home url in a language.
157	*
158	* @api
159	* @since 0.8
160	*
161	* @param string $lang Optional language code, defaults to the current language.
162	* @return string
163	*/
164	function pll_home_url( $lang = '' ) {
165	if ( empty( $lang ) ) {
166	$lang = pll_current_language();
167	}
168
169	if ( empty( $lang ) \|\| empty( PLL()->links ) ) {
170	return home_url( '/' );
171	}
172
173	return PLL()->links->get_home_url( $lang );
174	}
175
176	/**
177	* Registers a string for translation in the "strings translation" panel.
178	*
179	* @api
180	* @since 0.6
181	*
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
188	*/
189	function pll_register_string( $name, $string, $context = 'Polylang', $multiline = false ) {
190	if ( PLL() instanceof PLL_Admin_Base ) {
191	PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
192	}
193	}
194
195	/**
196	* Translates a string ( previously registered with pll_register_string ).
197	*
198	* @api
199	* @since 0.6
200	*
201	* @param string $string The string to translate.
202	* @return string The string translated in the current language.
203	*/
204	function pll__( $string ) {
205	if ( ! is_scalar( $string ) \|\| '' === $string ) {
206	return $string;
207	}
208
209	return __( $string, 'pll_string' ); // PHPCS:ignore WordPress.WP.I18n
210	}
211
212	/**
213	* Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
214	*
215	* @api
216	* @since 2.1
217	*
218	* @param string $string The string to translate.
219	* @return string The string translated in the current language.
220	*/
221	function pll_esc_html__( $string ) {
222	return esc_html( pll__( $string ) );
223	}
224
225	/**
226	* Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
227	*
228	* @api
229	* @since 2.1
230	*
231	* @param string $string The string to translate.
232	* @return string The string translated in the current language.
233	*/
234	function pll_esc_attr__( $string ) {
235	return esc_attr( pll__( $string ) );
236	}
237
238	/**
239	* Echoes a translated string ( previously registered with pll_register_string )
240	* It is an equivalent of _e() and is not escaped.
241	*
242	* @api
243	* @since 0.6
244	*
245	* @param string $string The string to translate.
246	* @return void
247	*/
248	function pll_e( $string ) {
249	echo pll__( $string ); // phpcs:ignore
250	}
251
252	/**
253	* Echoes a translated string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
254	*
255	* @api
256	* @since 2.1
257	*
258	* @param string $string The string to translate.
259	* @return void
260	*/
261	function pll_esc_html_e( $string ) {
262	echo pll_esc_html__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
263	}
264
265	/**
266	* Echoes a translated a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
267	*
268	* @api
269	* @since 2.1
270	*
271	* @param string $string The string to translate.
272	* @return void
273	*/
274	function pll_esc_attr_e( $string ) {
275	echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
276	}
277
278	/**
279	* Translates a string ( previously registered with pll_register_string ).
280	*
281	* @api
282	* @since 1.5.4
283	*
284	* @param string $string The string to translate.
285	* @param string $lang Language code.
286	* @return string The string translated in the requested language.
287	*/
288	function pll_translate_string( $string, $lang ) {
289	if ( PLL() instanceof PLL_Frontend && pll_current_language() === $lang ) {
290	return pll__( $string );
291	}
292
293	if ( ! is_scalar( $string ) \|\| '' === $string ) {
294	return $string;
295	}
296
297	$lang = PLL()->model->get_language( $lang );
298
299	if ( empty( $lang ) ) {
300	return $string;
301	}
302
303	static $cache; // Cache object to avoid loading the same translations object several times.
304
305	if ( empty( $cache ) ) {
306	$cache = new PLL_Cache();
307	}
308
309	$mo = $cache->get( $lang->slug );
310
311	if ( ! $mo instanceof PLL_MO ) {
312	$mo = new PLL_MO();
313	$mo->import_from_db( $lang );
314	$cache->set( $lang->slug, $mo );
315	}
316
317	return $mo->translate( $string );
318	}
319
320	/**
321	* Returns true if Polylang manages languages and translations for this post type.
322	*
323	* @api
324	* @since 1.0.1
325	*
326	* @param string $post_type Post type name.
327	* @return bool
328	*/
329	function pll_is_translated_post_type( $post_type ) {
330	return PLL()->model->is_translated_post_type( $post_type );
331	}
332
333	/**
334	* Returns true if Polylang manages languages and translations for this taxonomy.
335	*
336	* @api
337	* @since 1.0.1
338	*
339	* @param string $tax Taxonomy name.
340	* @return bool
341	*/
342	function pll_is_translated_taxonomy( $tax ) {
343	return PLL()->model->is_translated_taxonomy( $tax );
344	}
345
346	/**
347	* Returns the list of available languages.
348	*
349	* @api
350	* @since 1.5
351	*
352	* @param array $args {
353	* Optional array of arguments.
354	*
355	* @type bool $hide_empty Hides languages with no posts if set to true ( defaults to false ).
356	* @type string $fields Return only that field if set ( @see PLL_Language for a list of fields ), defaults to 'slug'.
357	* }
358	* @return string[]
359	*/
360	function pll_languages_list( $args = array() ) {
361	$args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
362	return PLL()->model->get_languages_list( $args );
363	}
364
365	/**
366	* Sets the post language.
367	*
368	* @api
369	* @since 1.5
370	* @since 3.4 $lang accepts PLL_Language or string.
371	* @since 3.4 Returns a boolean.
372	*
373	* @param int $id Post ID.
374	* @param PLL_Language\|string $lang Language (object or slug).
375	* @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
376	* the post).
377	*/
378	function pll_set_post_language( $id, $lang ) {
379	return PLL()->model->post->set_language( $id, $lang );
380	}
381
382	/**
383	* Sets the term language.
384	*
385	* @api
386	* @since 1.5
387	* @since 3.4 $lang accepts PLL_Language or string.
388	* @since 3.4 Returns a boolean.
389	*
390	* @param int $id Term ID.
391	* @param PLL_Language\|string $lang Language (object or slug).
392	* @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
393	* the term).
394	*/
395	function pll_set_term_language( $id, $lang ) {
396	return PLL()->model->term->set_language( $id, $lang );
397	}
398
399	/**
400	* Save posts translations.
401	*
402	* @api
403	* @since 1.5
404	* @since 3.4 Returns an associative array of translations.
405	*
406	* @param int[] $arr An associative array of translations with language code as key and post ID as value.
407	* @return int[] An associative array with language codes as key and post IDs as values.
408	*
409	* @phpstan-return array<non-empty-string, positive-int>
410	*/
411	function pll_save_post_translations( $arr ) {
412	$id = reset( $arr );
413	if ( $id ) {
414	return PLL()->model->post->save_translations( $id, $arr );
415	}
416
417	return array();
418	}
419
420	/**
421	* Save terms translations
422	*
423	* @api
424	* @since 1.5
425	* @since 3.4 Returns an associative array of translations.
426	*
427	* @param int[] $arr An associative array of translations with language code as key and term ID as value.
428	* @return int[] An associative array with language codes as key and term IDs as values.
429	*
430	* @phpstan-return array<non-empty-string, positive-int>
431	*/
432	function pll_save_term_translations( $arr ) {
433	$id = reset( $arr );
434	if ( $id ) {
435	return PLL()->model->term->save_translations( $id, $arr );
436	}
437
438	return array();
439	}
440
441	/**
442	* Returns the post language.
443	*
444	* @api
445	* @since 1.5.4
446	* @since 3.4 Accepts composite values for `$field`.
447	*
448	* @param int $post_id Post ID.
449	* @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
450	* Pass `\OBJECT` constant to get the language object. A composite value can be used for language
451	* term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
452	* {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
453	* @return string\|int\|bool\|string[]\|PLL_Language The requested field or object for the post language, `false` if no language is associated to that post.
454	*
455	* @phpstan-return (
456	* $field is \OBJECT ? PLL_Language : (
457	* $field is 'slug' ? non-empty-string : string\|int\|bool\|list<non-empty-string>
458	* )
459	* )\|false
460	*/
461	function pll_get_post_language( $post_id, $field = 'slug' ) {
462	$lang = PLL()->model->post->get_language( $post_id );
463
464	if ( empty( $lang ) \|\| \OBJECT === $field ) {
465	return $lang;
466	}
467
468	return $lang->get_prop( $field );
469	}
470
471	/**
472	* Returns the term language.
473	*
474	* @api
475	* @since 1.5.4
476	* @since 3.4 Accepts composite values for `$field`.
477	*
478	* @param int $term_id Term ID.
479	* @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
480	* Pass `\OBJECT` constant to get the language object. A composite value can be used for language
481	* term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
482	* {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
483	* @return string\|int\|bool\|string[]\|PLL_Language The requested field or object for the post language, `false` if no language is associated to that term.
484	*
485	* @phpstan-return (
486	* $field is \OBJECT ? PLL_Language : (
487	* $field is 'slug' ? non-empty-string : string\|int\|bool\|list<non-empty-string>
488	* )
489	* )\|false
490	*/
491	function pll_get_term_language( $term_id, $field = 'slug' ) {
492	$lang = PLL()->model->term->get_language( $term_id );
493
494	if ( empty( $lang ) \|\| \OBJECT === $field ) {
495	return $lang;
496	}
497
498	return $lang->get_prop( $field );
499	}
500
501	/**
502	* Returns an array of translations of a post.
503	*
504	* @api
505	* @since 1.8
506	*
507	* @param int $post_id Post ID.
508	* @return int[] An associative array of translations with language code as key and translation post ID as value.
509	*
510	* @phpstan-return array<non-empty-string, positive-int>
511	*/
512	function pll_get_post_translations( $post_id ) {
513	return PLL()->model->post->get_translations( $post_id );
514	}
515
516	/**
517	* Returns an array of translations of a term.
518	*
519	* @api
520	* @since 1.8
521	*
522	* @param int $term_id Term ID.
523	* @return int[] An associative array of translations with language code as key and translation term ID as value.
524	*
525	* @phpstan-return array<non-empty-string, positive-int>
526	*/
527	function pll_get_term_translations( $term_id ) {
528	return PLL()->model->term->get_translations( $term_id );
529	}
530
531	/**
532	* Counts posts in a language.
533	*
534	* @api
535	* @since 1.5
536	*
537	* @param string $lang Language code.
538	* @param array $args {
539	* Optional array of arguments.
540	*
541	* @type string $post_type Post type.
542	* @type int $m YearMonth ( ex: 201307 ).
543	* @type int $year 4 digit year.
544	* @type int $monthnum Month number (from 1 to 12).
545	* @type int $day Day of the month (from 1 to 31).
546	* @type int $author Author id.
547	* @type string $author_name Author nicename.
548	* @type string $post_format Post format.
549	* @type string $post_status Post status.
550	* }
551	* @return int Posts count.
552	*/
553	function pll_count_posts( $lang, $args = array() ) {
554	$lang = PLL()->model->get_language( $lang );
555
556	if ( empty( $lang ) ) {
557	return 0;
558	}
559
560	return PLL()->model->count_posts( $lang, $args );
561	}
562
563	/**
564	* Allows to access the Polylang instance.
565	* However, it is always preferable to use API functions
566	* as internal methods may be changed without prior notice.
567	*
568	* @since 1.8
569	*
570	* @return PLL_Frontend\|PLL_Admin\|PLL_Settings\|PLL_REST_Request
571	*/
572	function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
573	return $GLOBALS['polylang'];
574	}
575