<?php
/**
 * WordPress Coding Standard.
 *
 * @package WPCS\WordPressCodingStandards
 * @link    https://github.com/WordPress/WordPress-Coding-Standards
 * @license https://opensource.org/licenses/MIT MIT
 */

namespace WordPressCS\WordPress\Helpers;

use PHPCSUtils\BackCompat\Helper;

/**
 * Helper utilities for checking if a name is in snake_case.
 *
 * ---------------------------------------------------------------------------------------------
 * This class is only intended for internal use by WordPressCS and is not part of the public API.
 * This also means that it has no promise of backward compatibility. Use at your own risk.
 * ---------------------------------------------------------------------------------------------
 *
 * {@internal The functionality in this class will likely be replaced at some point in
 * the future by functions from PHPCSUtils.}
 *
 * @internal
 *
 * @since 3.0.0 The method in this class was previously contained in the
 *              `WordPressCS\WordPress\Sniff` class and has been moved here.
 */
final class SnakeCaseHelper {

	/**
	 * Transform the name of a PHP construct (function, variable etc) to one in snake_case.
	 *
	 * @since 2.0.0 Moved from the `WordPress.NamingConventions.ValidFunctionName` sniff
	 *              to this class, renamed from `get_name_suggestion` and made static
	 *              so it can also be used by classes which don't extend this class.
	 * @since 3.0.0 - Moved from the Sniff class to this class.
	 *              - Renamed from `get_snake_case_name_suggestion()` to `get_suggestion()`.
	 *
	 * @param string $name The construct name.
	 *
	 * @return string
	 */
	public static function get_suggestion( $name ) {
		$suggested = preg_replace( '`(?<!_|^)([A-Z])`', '_$1', $name );

		if ( preg_match( '`^[a-z0-9_]+$`i', $suggested ) === 1 ) {
			// If the name only contains ASCII characters, we can safely lowercase it.
			$suggested = strtolower( $suggested );
		} elseif ( function_exists( 'mb_strtolower' ) ) {
			$suggested = mb_strtolower( $suggested, Helper::getEncoding() );
		} else {
			// If the name contains non-ASCII chars and Mbstring is not available, only transliterate the ASCII chars.
			$suggested = strtr( $suggested, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz' );
		}

		return $suggested;
	}
}