<?php
/**
 * The Polylang public API.
 *
 * @package Polylang
 */

use WP_Syntex\Polylang\Switcher\Switcher;
use WP_Syntex\Polylang\Switcher\Settings\Settings;

/**
 * Template tag: displays the language switcher.
 * The function does nothing if used outside the frontend.
 *
 * @api
 * @since 0.5
 * @since 3.9 When the layout `select` is used, the value of each `option` is now always a URL, and the `data-lang`
 *            attributes are not added anymore.
 *            Returns `void` when printing the markup directly.
 *
 * @param array $args {
 *     Optional switcher settings.
 *
 *     @type string   $layout                 Layout of the switcher. Possible values are `horizontal`, `vertical`,
 *                                            `dropdown`, and `select`. Default is `vertical`.
 *     @type string   $alignment              Alignment of the items. Possible values are `left`, `center`, `right`,
 *                                            `stretched`. Default is `left` or `right`, depending on `is_rtl()`.
 *     @type bool     $show_wrapper           Display the wrapper or not. Default is `false` for legacy calls (list
 *                                            items only, or bare `<select>` for dropdown). Default is `true` when
 *                                            `layout` is `select`. Omitting this argument on a bare list call triggers
 *                                            a `_doing_it_wrong()` notice: pass `show_wrapper` => false explicitly to
 *                                            keep the current behavior.
 *     @type bool     $show_flags             Display the flags or not. Default is `false`.
 *     @type string   $flag_aspect_ratio      Flags aspect ratio. Possible values are `3:2` and `1:1`. Default is `3:2`.
 *     @type string   $show_labels            Display the labels. Possible values are an empty string (no labels),
 *                                            `names` (language names), `codes` (languages codes). Default is `names`.
 *     @type bool     $hide_if_empty          Hide languages that don't have any posts. Default is `true`.
 *     @type bool     $hide_if_no_translation Hide languages that don't have translations. Default is `false`.
 *     @type bool     $hide_current           Hide the current language. Default is `false`.
 *     @type bool     $force_home             Force elements to link to the home pages instead of the translations.
 *                                            Default is `false`.
 *     @type int      $post_id                Build the links according to the translations of the given post ID.
 *                                            Default is `0`.
 *     @type string[] $wrapper_classes        HTML classes to add to the wrapper. Default is an empty array.
 *     @type string[] $item_classes           HTML classes to add to each item. Default is an empty array.
 *     @type string[] $link_classes           HTML classes to add to each link. Default is an empty array.
 *     @type string   $unique_id              A unique identifier. Default is an empty string: a default unique
 *                                            identifier will be automatically generated.
 *     @type bool     $echo                   Whether to print the HTML markup or return it. Default is `true`.
 *     @type bool     $raw                    Whether to return a raw array instead of HTML markup. Default is `false`.
 * }
 * @return string|array|void Either the html markup of the switcher or the raw elements to build a custom language switcher.
 */
function pll_the_languages( $args = array() ) {
	if ( empty( PLL()->links ) ) {
		return empty( $args['raw'] ) ? '' : array();
	}

	if ( Settings::is_legacy( $args ) ) {
		_deprecated_argument(
			'pll_the_languages()',
			'3.9',
			'See the documentation of pll_the_languages()'
		);
	}

	if ( empty( $args['raw'] ) && ! isset( $args['show_wrapper'] ) ) {
		if ( ! isset( $args['layout'] ) ) {
			// Backward compatibility with Polylang < 3.9.
			$args['show_wrapper'] = false;

			if ( empty( $args['dropdown'] ) ) {
				_doing_it_wrong(
					'pll_the_languages()',
					'pll_the_languages() does not output a wrapper by default. Pass `show_wrapper` => false explicitly to keep this behavior. In a near future, pll_the_languages() will output a `<ul>` wrapper as well (i.e. `show_wrapper` will default to `true`).',
					'3.9'
				);
			}
		}
	}

	$settings = new Settings( $args );

	// Backward compatibility: legacy dropdown switchers ignored `hide_current` unless `raw` was set.
	$settings->hide_current = ! empty( $args['hide_current'] ) && ! ( ! empty( $args['dropdown'] ) && empty( $args['raw'] ) );

	$switcher = new Switcher( $settings, PLL()->links );

	if ( ! empty( $args['raw'] ) ) {
		$elements = array();

		foreach ( $switcher->get_elements() as $slug => $element ) {
			$language = PLL()->links->model->languages->get( $slug );

			if ( empty( $language ) ) {
				// Should not happen.
				continue;
			}

			$element = get_object_vars( $element );

			$element['is_rtl']         = 'rtl' === $element['direction'];
			$element['name']           = 'codes' === $settings->show_labels ? $element['slug'] : $language->name;
			$element['flag']           = ! empty( $settings->show_flags ) ? $element['flag'] : $language->get_display_flag_url();
			$element['current_lang']   = $element['is_current'];
			$element['no_translation'] = ! $element['has_translations'];
			$element['classes']        = $element['item_classes'];

			$elements[ $slug ] = $element;
		}

		return $elements;
	}

	if ( isset( $args['echo'] ) && empty( $args['echo'] ) ) {
		return $switcher->get();
	}

	$switcher->print();
}

/**
 * Returns the current language on frontend.
 * Returns the language set in admin language filter on backend (false if set to all languages).
 *
 * @api
 * @since 0.8.1
 * @since 3.4 Accepts composite values.
 *
 * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
 *                      Pass `\OBJECT` constant to get the language object. A composite value can be used for language
 *                      term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
 *                      {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
 * @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.
 *
 * @phpstan-return (
 *     $field is \OBJECT ? PLL_Language : (
 *         $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
 *     )
 * )|false
 */
function pll_current_language( $field = 'slug' ) {
	if ( empty( PLL()->curlang ) ) {
		return false;
	}

	if ( \OBJECT === $field ) {
		return PLL()->curlang;
	}

	return PLL()->curlang->get_prop( $field );
}

/**
 * Returns the default language.
 *
 * @api
 * @since 1.0
 * @since 3.4 Accepts composite values.
 *
 * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
 *                      Pass `\OBJECT` constant to get the language object. A composite value can be used for language
 *                      term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
 *                      {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
 * @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.
 *
 * @phpstan-return (
 *     $field is \OBJECT ? PLL_Language : (
 *         $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
 *     )
 * )|false
 */
function pll_default_language( $field = 'slug' ) {
	$lang = PLL()->model->get_default_language();

	if ( empty( $lang ) ) {
		return false;
	}

	if ( \OBJECT === $field ) {
		return $lang;
	}

	return $lang->get_prop( $field );
}

/**
 * Among the post and its translations, returns the ID of the post which is in the language represented by $lang.
 *
 * @api
 * @since 0.5
 * @since 3.4 Returns `0` instead of `false` if not translated or if the post has no language.
 * @since 3.4 $lang accepts `PLL_Language` or string.
 *
 * @param int                 $post_id Post ID.
 * @param PLL_Language|string $lang    Optional language (object or slug), defaults to the current language.
 * @return int The translation post ID if exists. 0 if not translated, the post has no language or if the language doesn't exist.
 *
 * @phpstan-return int<0, max>
 */
function pll_get_post( $post_id, $lang = '' ) {
	$lang = $lang ?: pll_current_language();

	if ( empty( $lang ) ) {
		return 0;
	}

	return PLL()->model->post->get( $post_id, $lang );
}

/**
 * Among the term and its translations, returns the ID of the term which is in the language represented by $lang.
 *
 * @api
 * @since 0.5
 * @since 3.4 Returns `0` instead of `false` if not translated or if the term has no language.
 * @since 3.4 $lang accepts PLL_Language or string.
 *
 * @param int                 $term_id Term ID.
 * @param PLL_Language|string $lang    Optional language (object or slug), defaults to the current language.
 * @return int The translation term ID if exists. 0 if not translated, the term has no language or if the language doesn't exist.
 *
 * @phpstan-return int<0, max>
 */
function pll_get_term( $term_id, $lang = '' ) {
	$lang = $lang ?: pll_current_language();

	if ( empty( $lang ) ) {
		return 0;
	}

	return PLL()->model->term->get( $term_id, $lang );
}

/**
 * Returns the home url in a language.
 *
 * @api
 * @since 0.8
 *
 * @param string $lang Optional language code, defaults to the current language.
 * @return string
 */
function pll_home_url( $lang = '' ) {
	if ( empty( $lang ) ) {
		$lang = pll_current_language();
	}

	if ( empty( $lang ) || empty( PLL()->links ) ) {
		return home_url( '/' );
	}

	return PLL()->links->get_home_url( $lang );
}

/**
 * Registers a string for translation in the "strings translation" panel.
 *
 * @api
 * @since 0.6
 *
 * @param string $name      A unique name for the string.
 * @param string $string    The string to register.
 * @param string $context   Optional, the group in which the string is registered, defaults to 'polylang'.
 * @param bool   $multiline Optional, true if the string table should display a multiline textarea,
 *                          false if should display a single line input, defaults to false.
 * @return void
 */
function pll_register_string( $name, $string, $context = 'Polylang', $multiline = false ) {
	if ( PLL() instanceof PLL_Admin_Base ) {
		PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
	}
}

/**
 * Translates a string ( previously registered with pll_register_string ).
 *
 * @api
 * @since 0.6
 *
 * @param string $string The string to translate.
 * @return string The string translated in the current language.
 */
function pll__( $string ) {
	if ( ! is_scalar( $string ) || '' === $string ) {
		return $string;
	}

	return __( $string, 'pll_string' ); // PHPCS:ignore WordPress.WP.I18n
}

/**
 * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
 *
 * @api
 * @since 2.1
 *
 * @param string $string The string to translate.
 * @return string The string translated in the current language.
 */
function pll_esc_html__( $string ) {
	return esc_html( pll__( $string ) );
}

/**
 * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
 *
 * @api
 * @since 2.1
 *
 * @param string $string The string to translate.
 * @return string The string translated in the current language.
 */
function pll_esc_attr__( $string ) {
	return esc_attr( pll__( $string ) );
}

/**
 * Echoes a translated string ( previously registered with pll_register_string )
 * It is an equivalent of _e() and is not escaped.
 *
 * @api
 * @since 0.6
 *
 * @param string $string The string to translate.
 * @return void
 */
function pll_e( $string ) {
	echo pll__( $string ); // phpcs:ignore
}

/**
 * Echoes a translated string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
 *
 * @api
 * @since 2.1
 *
 * @param string $string The string to translate.
 * @return void
 */
function pll_esc_html_e( $string ) {
	echo pll_esc_html__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
}

/**
 * Echoes a translated a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
 *
 * @api
 * @since 2.1
 *
 * @param string $string The string to translate.
 * @return void
 */
function pll_esc_attr_e( $string ) {
	echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
}

/**
 * Translates a string ( previously registered with pll_register_string ).
 *
 * @api
 * @since 1.5.4
 *
 * @param string $string The string to translate.
 * @param string $lang   Language code.
 * @return string The string translated in the requested language.
 */
function pll_translate_string( $string, $lang ) {
	if ( PLL() instanceof PLL_Frontend && pll_current_language() === $lang ) {
		return pll__( $string );
	}

	if ( ! is_scalar( $string ) || '' === $string ) {
		return $string;
	}

	$lang = PLL()->model->get_language( $lang );

	if ( empty( $lang ) ) {
		return $string;
	}

	$mo = new PLL_MO();
	$mo->import_from_db( $lang );

	return $mo->translate( $string );
}

/**
 * Returns true if Polylang manages languages and translations for this post type.
 *
 * @api
 * @since 1.0.1
 *
 * @param string $post_type Post type name.
 * @return bool
 */
function pll_is_translated_post_type( $post_type ) {
	return PLL()->model->is_translated_post_type( $post_type );
}

/**
 * Returns true if Polylang manages languages and translations for this taxonomy.
 *
 * @api
 * @since 1.0.1
 *
 * @param string $tax Taxonomy name.
 * @return bool
 */
function pll_is_translated_taxonomy( $tax ) {
	return PLL()->model->is_translated_taxonomy( $tax );
}

/**
 * Returns the list of available languages.
 *
 * @api
 * @since 1.5
 *
 * @param array $args {
 *   Optional array of arguments.
 *
 *   @type bool   $hide_empty Hides languages with no posts if set to true ( defaults to false ).
 *   @type string $fields     Return only that field if set ( @see PLL_Language for a list of fields ), defaults to 'slug'.
 * }
 * @return string[]
 */
function pll_languages_list( $args = array() ) {
	$args         = wp_parse_args( $args, array( 'fields' => 'slug' ) );
	$hide_empty   = ! empty( $args['hide_empty'] ) ? 'hide_empty' : '';
	$hide_default = ! empty( $args['hide_default'] ) ? 'hide_default' : '';
	unset( $args['hide_empty'], $args['hide_default'] );

	return PLL()->model->languages
		->filter( $hide_empty )
		->filter( $hide_default )
		->get_list( $args );
}

/**
 * Sets the post language.
 *
 * @api
 * @since 1.5
 * @since 3.4 $lang accepts PLL_Language or string.
 * @since 3.4 Returns a boolean.
 *
 * @param int                 $id   Post ID.
 * @param PLL_Language|string $lang Language (object or slug).
 * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
 *              the post).
 */
function pll_set_post_language( $id, $lang ) {
	return PLL()->model->post->set_language( $id, $lang );
}

/**
 * Sets the term language.
 *
 * @api
 * @since 1.5
 * @since 3.4 $lang accepts PLL_Language or string.
 * @since 3.4 Returns a boolean.
 *
 * @param int                 $id   Term ID.
 * @param PLL_Language|string $lang Language (object or slug).
 * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to
 *              the term).
 */
function pll_set_term_language( $id, $lang ) {
	return PLL()->model->term->set_language( $id, $lang );
}

/**
 * Save posts translations.
 *
 * @api
 * @since 1.5
 * @since 3.4 Returns an associative array of translations.
 *
 * @param int[] $arr An associative array of translations with language code as key and post ID as value.
 * @return int[] An associative array with language codes as key and post IDs as values.
 *
 * @phpstan-return array<non-empty-string, positive-int>
 */
function pll_save_post_translations( $arr ) {
	$id = reset( $arr );
	if ( $id ) {
		return PLL()->model->post->save_translations( $id, $arr );
	}

	return array();
}

/**
 * Save terms translations
 *
 * @api
 * @since 1.5
 * @since 3.4 Returns an associative array of translations.
 *
 * @param int[] $arr An associative array of translations with language code as key and term ID as value.
 * @return int[] An associative array with language codes as key and term IDs as values.
 *
 * @phpstan-return array<non-empty-string, positive-int>
 */
function pll_save_term_translations( $arr ) {
	$id = reset( $arr );
	if ( $id ) {
		return PLL()->model->term->save_translations( $id, $arr );
	}

	return array();
}

/**
 * Returns the post language.
 *
 * @api
 * @since 1.5.4
 * @since 3.4 Accepts composite values for `$field`.
 *
 * @param int    $post_id Post ID.
 * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
 *                      Pass `\OBJECT` constant to get the language object. A composite value can be used for language
 *                      term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
 *                      {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
 * @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.
 *
 * @phpstan-return (
 *     $field is \OBJECT ? PLL_Language : (
 *         $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
 *     )
 * )|false
 */
function pll_get_post_language( $post_id, $field = 'slug' ) {
	$lang = PLL()->model->post->get_language( $post_id );

	if ( empty( $lang ) || \OBJECT === $field ) {
		return $lang;
	}

	return $lang->get_prop( $field );
}

/**
 * Returns the term language.
 *
 * @api
 * @since 1.5.4
 * @since 3.4 Accepts composite values for `$field`.
 *
 * @param int    $term_id Term ID.
 * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`.
 *                      Pass `\OBJECT` constant to get the language object. A composite value can be used for language
 *                      term property values, in the form of `{language_taxonomy_name}:{property_name}` (see
 *                      {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`.
 * @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.
 *
 * @phpstan-return (
 *     $field is \OBJECT ? PLL_Language : (
 *         $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string>
 *     )
 * )|false
 */
function pll_get_term_language( $term_id, $field = 'slug' ) {
	$lang = PLL()->model->term->get_language( $term_id );

	if ( empty( $lang ) || \OBJECT === $field ) {
		return $lang;
	}

	return $lang->get_prop( $field );
}

/**
 * Returns an array of translations of a post.
 *
 * @api
 * @since 1.8
 *
 * @param int $post_id Post ID.
 * @return int[] An associative array of translations with language code as key and translation post ID as value.
 *
 * @phpstan-return array<non-empty-string, positive-int>
 */
function pll_get_post_translations( $post_id ) {
	return PLL()->model->post->get_translations( $post_id );
}

/**
 * Returns an array of translations of a term.
 *
 * @api
 * @since 1.8
 *
 * @param int $term_id Term ID.
 * @return int[] An associative array of translations with language code as key and translation term ID as value.
 *
 * @phpstan-return array<non-empty-string, positive-int>
 */
function pll_get_term_translations( $term_id ) {
	return PLL()->model->term->get_translations( $term_id );
}

/**
 * Counts posts in a language.
 *
 * @api
 * @since 1.5
 *
 * @param string $lang Language code.
 * @param array  $args {
 *   Optional array of arguments.
 *
 *   @type string $post_type   Post type.
 *   @type int    $m           YearMonth ( ex: 201307 ).
 *   @type int    $year        4 digit year.
 *   @type int    $monthnum    Month number (from 1 to 12).
 *   @type int    $day         Day of the month (from 1 to 31).
 *   @type int    $author      Author id.
 *   @type string $author_name Author nicename.
 *   @type string $post_format Post format.
 *   @type string $post_status Post status.
 * }
 * @return int Posts count.
 */
function pll_count_posts( $lang, $args = array() ) {
	$lang = PLL()->model->get_language( $lang );

	if ( empty( $lang ) ) {
		return 0;
	}

	return PLL()->model->count_posts( $lang, $args );
}

/**
 * Wraps `wp_insert_post` with language feature.
 *
 * @since 3.7
 *
 * @param array               $postarr {
 *     An array of elements that make up a post to insert.
 *     @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments.
 *
 *     @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values.
 * }
 * @param PLL_Language|string $language The post language object or slug.
 * @return int|WP_Error The post ID on success. The value `WP_Error` on failure.
 */
function pll_insert_post( array $postarr, $language ) {
	$language = PLL()->model->get_language( $language );

	if ( ! $language instanceof PLL_Language ) {
		return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) );
	}

	return PLL()->model->post->insert( $postarr, $language );
}

/**
 * Wraps `wp_insert_term` with language feature.
 *
 * @since 3.7
 *
 * @param string              $term     The term name to add.
 * @param string              $taxonomy The taxonomy to which to add the term.
 * @param PLL_Language|string $language The term language object or slug.
 * @param array               $args {
 *     Optional. Array of arguments for inserting a term.
 *
 *     @type string   $alias_of     Slug of the term to make this term an alias of.
 *                                  Default empty string. Accepts a term slug.
 *     @type string   $description  The term description. Default empty string.
 *     @type int      $parent       The id of the parent term. Default 0.
 *     @type string   $slug         The term slug to use. Default empty string.
 *     @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values.
 * }
 * @return array|WP_Error {
 *     An array of the new term data, `WP_Error` otherwise.
 *
 *     @type int        $term_id          The new term ID.
 *     @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
 * }
 */
function pll_insert_term( string $term, string $taxonomy, $language, array $args = array() ) {
	$language = PLL()->model->get_language( $language );

	if ( ! $language instanceof PLL_Language ) {
		return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) );
	}

	return PLL()->model->term->insert( $term, $taxonomy, $language, $args );
}

/**
 * Wraps `wp_update_post` with language feature.
 *
 * @since 3.7
 *
 * @param array $postarr {
 *     Optional. An array of elements that make up a post to update.
 *     @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments.
 *
 *     @type PLL_Language|string $lang         The post language object or slug.
 *     @type string[]            $translations The translation group to assign to the post with language slug as keys and post ID as values.
 * }
 * @return int|WP_Error The post ID on success. The value `WP_Error` on failure.
 */
function pll_update_post( array $postarr ) {
	return PLL()->model->post->update( $postarr );
}

/**
 * Wraps `wp_update_term` with language feature.
 *
 * @since 3.7
 *
 * @param int   $term_id The ID of the term.
 * @param array $args {
 *     Optional. Array of arguments for updating a term.
 *
 *     @type string              $alias_of     Slug of the term to make this term an alias of.
 *                                             Default empty string. Accepts a term slug.
 *     @type string              $description  The term description. Default empty string.
 *     @type int                 $parent       The id of the parent term. Default 0.
 *     @type string              $slug         The term slug to use. Default empty string.
 *     @type string              $name         The term name.
 *     @type PLL_Language|string $lang         The term language object or slug.
 *     @type string[]            $translations The translation group to assign to the term with language slug as keys and `term_id` as values.
 * }
 * @return array|WP_Error {
 *     An array containing the `term_id` and `term_taxonomy_id`, `WP_Error` otherwise.
 *
 *     @type int        $term_id          The new term ID.
 *     @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
 * }
 */
function pll_update_term( int $term_id, array $args = array() ) {
	return PLL()->model->term->update( $term_id, $args );
}

/**
 * Allows to access the Polylang instance.
 * However, it is always preferable to use API functions
 * as internal methods may be changed without prior notice.
 *
 * @since 1.8
 *
 * @return PLL_Frontend|PLL_Admin|PLL_Settings|PLL_REST_Request
 */
function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
	return $GLOBALS['polylang'];
}