<?php

namespace WPForms\Helpers;

/**
 * Template related helper methods.
 *
 * @since 1.5.4
 */
class Templates {

	/**
	 * Return a list of paths to check for template locations
	 *
	 * @since 1.5.4
	 *
	 * @return array
	 */
	public static function get_theme_template_paths() {

		$template_dir = 'wpforms';

		$file_paths = array(
			1   => \trailingslashit( \get_stylesheet_directory() ) . $template_dir,
			10  => \trailingslashit( \get_template_directory() ) . $template_dir,
			100 => \trailingslashit( \WPFORMS_PLUGIN_DIR ) . 'templates',
		);

		$file_paths = \apply_filters( 'wpforms_helpers_templates_get_theme_template_paths', $file_paths );

		// Sort the file paths based on priority.
		\ksort( $file_paths, SORT_NUMERIC );

		return \array_map( 'trailingslashit', $file_paths );
	}

	/**
	 * Locate a template and return the path for inclusion.
	 *
	 * @since 1.5.4
	 *
	 * @param string $template_name Template name.
	 *
	 * @return string
	 */
	public static function locate( $template_name ) {

		// Trim off any slashes from the template name.
		$template_name = \ltrim( $template_name, '/' );

		if ( empty( $template_name ) ) {
			return \apply_filters( 'wpforms_helpers_templates_locate', '', $template_name );
		}

		$located = '';

		// Try locating this template file by looping through the template paths.
		foreach ( self::get_theme_template_paths() as $template_path ) {
			if ( \file_exists( $template_path . $template_name ) ) {
				$located = $template_path . $template_name;
				break;
			}
		}

		return \apply_filters( 'wpforms_helpers_templates_locate', $located, $template_name );
	}

	/**
	 * Include a template.
	 * Uses 'require' if $args are passed or 'load_template' if not.
	 *
	 * @since 1.5.4
	 *
	 * @param string $template_name Template name.
	 * @param array  $args          Arguments.
	 * @param bool   $extract       Extract arguments.
	 *
	 * @throws \RuntimeException If extract() tries to modify the scope.
	 */
	public static function include_html( $template_name, $args = array(), $extract = false ) {

		$template_name .= '.php';

		// Allow 3rd party plugins to filter template file from their plugin.
		$located = \apply_filters( 'wpforms_helpers_templates_include_html_located', self::locate( $template_name ), $template_name, $args, $extract );
		$args    = \apply_filters( 'wpforms_helpers_templates_include_html_args', $args, $template_name, $extract );

		if ( empty( $located ) || ! \is_readable( $located ) ) {
			return;
		}

		// Load template WP way if no arguments were passed.
		if ( empty( $args ) ) {
			\load_template( $located, false );
			return;
		}

		$extract = \apply_filters( 'wpforms_helpers_templates_include_html_extract_args', $extract, $template_name, $args );

		if ( $extract && \is_array( $args ) ) {

			$created_vars_count = extract( $args, EXTR_SKIP ); // phpcs:ignore WordPress.PHP.DontExtract

			// Protecting existing scope from modification.
			if ( count( $args ) !== $created_vars_count ) {
				throw new \RuntimeException( 'Extraction failed: variable names are clashing with the existing ones.' );
			}
		}

		require $located;
	}

	/**
	 * Like self::include_html, but returns the HTML instead of including.
	 *
	 * @since 1.5.4
	 *
	 * @param string $template_name Template name.
	 * @param array  $args          Arguments.
	 * @param bool   $extract       Extract arguments.
	 *
	 * @return string
	 */
	public static function get_html( $template_name, $args = array(), $extract = false ) {

		\ob_start();
		self::include_html( $template_name, $args, $extract );
		return \ob_get_clean();
	}
}
