polylang / src / api.php

api.php in Polylang 3.8.8, at src/api.php

677 lines 21.8 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` if not translated or if the post has no language.
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 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>
120	*/
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 );
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` if not translated or if the term has no language.
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 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>
144	*/
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 );
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	$mo = new PLL_MO();
304	$mo->import_from_db( $lang );
305
306	return $mo->translate( $string );
307	}
308
309	/**
310	* Returns true if Polylang manages languages and translations for this post type.
311	*
312	* @api
313	* @since 1.0.1
314	*
315	* @param string $post_type Post type name.
316	* @return bool
317	*/
318	function pll_is_translated_post_type( $post_type ) {
319	return PLL()->model->is_translated_post_type( $post_type );
320	}
321
322	/**
323	* Returns true if Polylang manages languages and translations for this taxonomy.
324	*
325	* @api
326	* @since 1.0.1
327	*
328	* @param string $tax Taxonomy name.
329	* @return bool
330	*/
331	function pll_is_translated_taxonomy( $tax ) {
332	return PLL()->model->is_translated_taxonomy( $tax );
333	}
334
335	/**
336	* Returns the list of available languages.
337	*
338	* @api
339	* @since 1.5
340	*
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[]
348	*/
349	function pll_languages_list( $args = array() ) {
350	$args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
351	$hide_empty = ! empty( $args['hide_empty'] ) ? 'hide_empty' : '';
352	$hide_default = ! empty( $args['hide_default'] ) ? 'hide_default' : '';
353	unset( $args['hide_empty'], $args['hide_default'] );
354
355	return PLL()->model->languages
356	->filter( $hide_empty )
357	->filter( $hide_default )
358	->get_list( $args );
359	}
360
361	/**
362	* Sets the post language.
363	*
364	* @api
365	* @since 1.5
366	* @since 3.4 $lang accepts PLL_Language or string.
367	* @since 3.4 Returns a boolean.
368	*
369	* @param int $id Post ID.
370	* @param PLL_Language\|string $lang Language (object or slug).
371	* @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
372	* the post).
373	*/
374	function pll_set_post_language( $id, $lang ) {
375	return PLL()->model->post->set_language( $id, $lang );
376	}
377
378	/**
379	* Sets the term language.
380	*
381	* @api
382	* @since 1.5
383	* @since 3.4 $lang accepts PLL_Language or string.
384	* @since 3.4 Returns a boolean.
385	*
386	* @param int $id Term ID.
387	* @param PLL_Language\|string $lang Language (object or slug).
388	* @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
389	* the term).
390	*/
391	function pll_set_term_language( $id, $lang ) {
392	return PLL()->model->term->set_language( $id, $lang );
393	}
394
395	/**
396	* Save posts translations.
397	*
398	* @api
399	* @since 1.5
400	* @since 3.4 Returns an associative array of translations.
401	*
402	* @param int[] $arr An associative array of translations with language code as key and post ID as value.
403	* @return int[] An associative array with language codes as key and post IDs as values.
404	*
405	* @phpstan-return array<non-empty-string, positive-int>
406	*/
407	function pll_save_post_translations( $arr ) {
408	$id = reset( $arr );
409	if ( $id ) {
410	return PLL()->model->post->save_translations( $id, $arr );
411	}
412
413	return array();
414	}
415
416	/**
417	* Save terms translations
418	*
419	* @api
420	* @since 1.5
421	* @since 3.4 Returns an associative array of translations.
422	*
423	* @param int[] $arr An associative array of translations with language code as key and term ID as value.
424	* @return int[] An associative array with language codes as key and term IDs as values.
425	*
426	* @phpstan-return array<non-empty-string, positive-int>
427	*/
428	function pll_save_term_translations( $arr ) {
429	$id = reset( $arr );
430	if ( $id ) {
431	return PLL()->model->term->save_translations( $id, $arr );
432	}
433
434	return array();
435	}
436
437	/**
438	* Returns the post language.
439	*
440	* @api
441	* @since 1.5.4
442	* @since 3.4 Accepts composite values for `$field`.
443	*
444	* @param int $post_id Post ID.
445	* @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
446	* Pass `\OBJECT` constant to get the language object. A composite value can be used for language
447	* term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
448	* {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
449	* @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.
450	*
451	* @phpstan-return (
452	* $field is \OBJECT ? PLL_Language : (
453	* $field is 'slug' ? non-empty-string : string\|int\|bool\|list<non-empty-string>
454	* )
455	* )\|false
456	*/
457	function pll_get_post_language( $post_id, $field = 'slug' ) {
458	$lang = PLL()->model->post->get_language( $post_id );
459
460	if ( empty( $lang ) \|\| \OBJECT === $field ) {
461	return $lang;
462	}
463
464	return $lang->get_prop( $field );
465	}
466
467	/**
468	* Returns the term language.
469	*
470	* @api
471	* @since 1.5.4
472	* @since 3.4 Accepts composite values for `$field`.
473	*
474	* @param int $term_id Term ID.
475	* @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
476	* Pass `\OBJECT` constant to get the language object. A composite value can be used for language
477	* term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
478	* {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
479	* @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.
480	*
481	* @phpstan-return (
482	* $field is \OBJECT ? PLL_Language : (
483	* $field is 'slug' ? non-empty-string : string\|int\|bool\|list<non-empty-string>
484	* )
485	* )\|false
486	*/
487	function pll_get_term_language( $term_id, $field = 'slug' ) {
488	$lang = PLL()->model->term->get_language( $term_id );
489
490	if ( empty( $lang ) \|\| \OBJECT === $field ) {
491	return $lang;
492	}
493
494	return $lang->get_prop( $field );
495	}
496
497	/**
498	* Returns an array of translations of a post.
499	*
500	* @api
501	* @since 1.8
502	*
503	* @param int $post_id Post ID.
504	* @return int[] An associative array of translations with language code as key and translation post ID as value.
505	*
506	* @phpstan-return array<non-empty-string, positive-int>
507	*/
508	function pll_get_post_translations( $post_id ) {
509	return PLL()->model->post->get_translations( $post_id );
510	}
511
512	/**
513	* Returns an array of translations of a term.
514	*
515	* @api
516	* @since 1.8
517	*
518	* @param int $term_id Term ID.
519	* @return int[] An associative array of translations with language code as key and translation term ID as value.
520	*
521	* @phpstan-return array<non-empty-string, positive-int>
522	*/
523	function pll_get_term_translations( $term_id ) {
524	return PLL()->model->term->get_translations( $term_id );
525	}
526
527	/**
528	* Counts posts in a language.
529	*
530	* @api
531	* @since 1.5
532	*
533	* @param string $lang Language code.
534	* @param array $args {
535	* Optional array of arguments.
536	*
537	* @type string $post_type Post type.
538	* @type int $m YearMonth ( ex: 201307 ).
539	* @type int $year 4 digit year.
540	* @type int $monthnum Month number (from 1 to 12).
541	* @type int $day Day of the month (from 1 to 31).
542	* @type int $author Author id.
543	* @type string $author_name Author nicename.
544	* @type string $post_format Post format.
545	* @type string $post_status Post status.
546	* }
547	* @return int Posts count.
548	*/
549	function pll_count_posts( $lang, $args = array() ) {
550	$lang = PLL()->model->get_language( $lang );
551
552	if ( empty( $lang ) ) {
553	return 0;
554	}
555
556	return PLL()->model->count_posts( $lang, $args );
557	}
558
559	/**
560	* Wraps `wp_insert_post` with language feature.
561	*
562	* @since 3.7
563	*
564	* @param array $postarr {
565	* An array of elements that make up a post to insert.
566	* @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments.
567	*
568	* @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values.
569	* }
570	* @param PLL_Language\|string $language The post language object or slug.
571	* @return int\|WP_Error The post ID on success. The value `WP_Error` on failure.
572	*/
573	function pll_insert_post( array $postarr, $language ) {
574	$language = PLL()->model->get_language( $language );
575
576	if ( ! $language instanceof PLL_Language ) {
577	return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) );
578	}
579
580	return PLL()->model->post->insert( $postarr, $language );
581	}
582
583	/**
584	* Wraps `wp_insert_term` with language feature.
585	*
586	* @since 3.7
587	*
588	* @param string $term The term name to add.
589	* @param string $taxonomy The taxonomy to which to add the term.
590	* @param PLL_Language\|string $language The term language object or slug.
591	* @param array $args {
592	* Optional. Array of arguments for inserting a term.
593	*
594	* @type string $alias_of Slug of the term to make this term an alias of.
595	* Default empty string. Accepts a term slug.
596	* @type string $description The term description. Default empty string.
597	* @type int $parent The id of the parent term. Default 0.
598	* @type string $slug The term slug to use. Default empty string.
599	* @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values.
600	* }
601	* @return array\|WP_Error {
602	* An array of the new term data, `WP_Error` otherwise.
603	*
604	* @type int $term_id The new term ID.
605	* @type int\|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
606	* }
607	*/
608	function pll_insert_term( string $term, string $taxonomy, $language, array $args = array() ) {
609	$language = PLL()->model->get_language( $language );
610
611	if ( ! $language instanceof PLL_Language ) {
612	return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) );
613	}
614
615	return PLL()->model->term->insert( $term, $taxonomy, $language, $args );
616	}
617
618	/**
619	* Wraps `wp_update_post` with language feature.
620	*
621	* @since 3.7
622	*
623	* @param array $postarr {
624	* Optional. An array of elements that make up a post to update.
625	* @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments.
626	*
627	* @type PLL_Language\|string $lang The post language object or slug.
628	* @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values.
629	* }
630	* @return int\|WP_Error The post ID on success. The value `WP_Error` on failure.
631	*/
632	function pll_update_post( array $postarr ) {
633	return PLL()->model->post->update( $postarr );
634	}
635
636	/**
637	* Wraps `wp_update_term` with language feature.
638	*
639	* @since 3.7
640	*
641	* @param int $term_id The ID of the term.
642	* @param array $args {
643	* Optional. Array of arguments for updating a term.
644	*
645	* @type string $alias_of Slug of the term to make this term an alias of.
646	* Default empty string. Accepts a term slug.
647	* @type string $description The term description. Default empty string.
648	* @type int $parent The id of the parent term. Default 0.
649	* @type string $slug The term slug to use. Default empty string.
650	* @type string $name The term name.
651	* @type PLL_Language\|string $lang The term language object or slug.
652	* @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values.
653	* }
654	* @return array\|WP_Error {
655	* An array containing the `term_id` and `term_taxonomy_id`, `WP_Error` otherwise.
656	*
657	* @type int $term_id The new term ID.
658	* @type int\|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
659	* }
660	*/
661	function pll_update_term( int $term_id, array $args = array() ) {
662	return PLL()->model->term->update( $term_id, $args );
663	}
664
665	/**
666	* Allows to access the Polylang instance.
667	* However, it is always preferable to use API functions
668	* as internal methods may be changed without prior notice.
669	*
670	* @since 1.8
671	*
672	* @return PLL_Frontend\|PLL_Admin\|PLL_Settings\|PLL_REST_Request
673	*/
674	function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
675	return $GLOBALS['polylang'];
676	}
677