<?php
/**
 * SQL text for statements that are written out rather than run.
 *
 * @package Shiftora\Support\Db
 */

declare(strict_types=1);

namespace Shiftora\Support\Db;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * A dump or a bulk INSERT is text that another database reads later, so it
 * cannot go through prepare() one row at a time. This is the single place that
 * turns a value or a name into SQL for it, on WordPress's own escaping.
 */
final class SqlLiteral {

	/**
	 * One value as an SQL literal: NULL as NULL, numbers bare, bytes as 0x hex,
	 * everything else quoted.
	 *
	 * Binary columns go as hex because quoted, non-UTF-8 bytes (a packed IP, a
	 * hash, geometry) would be cut at the first bad byte under the destination's
	 * charset.
	 */
	public static function value( mixed $value, bool $binary = false ): string {
		if ( null === $value ) {
			return 'NULL';
		}

		if ( is_int( $value ) ) {
			return (string) $value;
		}

		if ( is_float( $value ) ) {
			return is_finite( $value ) ? rtrim( rtrim( sprintf( '%.17F', $value ), '0' ), '.' ) : 'NULL';
		}

		if ( is_bool( $value ) ) {
			return $value ? '1' : '0';
		}

		$value = (string) $value;

		if ( $binary ) {
			return '' === $value ? "''" : '0x' . bin2hex( $value );
		}

		return self::string( $value );
	}

	/**
	 * Text in single quotes. esc_sql() hides '%' behind a salted token so
	 * prepare() cannot read it as a placeholder; that token is keyed to this
	 * site, so it is taken out again before the text leaves.
	 */
	public static function string( string $value ): string {
		global $wpdb;

		self::assert_backslash_escapes( $wpdb );

		return "'" . $wpdb->remove_placeholder_escape( (string) esc_sql( $value ) ) . "'";
	}

	/**
	 * What the session reads as sql_mode now, remembered per connection until
	 * SessionSqlMode changes it.
	 *
	 * @var \WeakMap<\wpdb, string>|null
	 */
	private static ?\WeakMap $session_modes = null;

	/** Tells the helper the session mode changed; $mode is the new one, or null to read it again. */
	public static function session_mode_changed( \wpdb $wpdb, ?string $mode = null ): void {
		self::$session_modes ??= new \WeakMap();

		if ( null === $mode ) {
			unset( self::$session_modes[ $wpdb ] );
			return;
		}

		self::$session_modes[ $wpdb ] = $mode;
	}

	/**
	 * esc_sql() escapes for the session it runs in. Under NO_BACKSLASH_ESCAPES it
	 * only doubles quotes, but the importer and the restorer on the other side
	 * read a backslash as an escape, so a value ending in one would close its
	 * quote there and let the rest run as SQL.
	 *
	 * @throws \RuntimeException When the session does not treat a backslash as an escape.
	 */
	private static function assert_backslash_escapes( \wpdb $wpdb ): void {
		self::$session_modes ??= new \WeakMap();

		if ( ! isset( self::$session_modes[ $wpdb ] ) ) {
			// phpcs:ignore WordPress.DB.DirectDatabaseQuery -- server metadata, nothing to cache
			self::$session_modes[ $wpdb ] = (string) ( $wpdb->get_var( 'SELECT @@SESSION.sql_mode' ) ?? '' );
		}

		if ( str_contains( strtoupper( self::$session_modes[ $wpdb ] ), 'NO_BACKSLASH_ESCAPES' ) ) {
			throw new \RuntimeException( 'Refused to write an SQL literal: the session runs with NO_BACKSLASH_ESCAPES, so quotes would be escaped the way the receiving side does not read them.' );
		}
	}

	/** A table or column name in backticks, with any backtick in it doubled. */
	public static function identifier( string $name ): string {
		return '`' . str_replace( '`', '``', $name ) . '`';
	}

	/**
	 * A comma separated column list.
	 *
	 * @param string[] $names Column names.
	 */
	public static function identifiers( array $names ): string {
		return implode( ', ', array_map( [ self::class, 'identifier' ], $names ) );
	}
}