Consolidate SQLite identifier escaping in WP_SQLite_Connection, improve docs

Author: JanJakes

wp-includes/sqlite-ast/class-wp-sqlite-connection.php

@@ -137,6 +137,47 @@ public function quote( $value, int $type = PDO::PARAM_STR ): string {
 		return $this->pdo->quote( $value, $type );
 	}
 
+	/**
+	 * Quote an SQLite identifier.
+	 *
+	 * Wraps the identifier in backticks and escapes backtick characters within.
+	 *
+	 * ---
+	 *
+	 * Quoted identifiers in SQLite are represented by string constants:
+	 *
+	 *   A string constant is formed by enclosing the string in single quotes (').
+	 *   A single quote within the string can be encoded by putting two single
+	 *   quotes in a row - as in Pascal. C-style escapes using the backslash
+	 *   character are not supported because they are not standard SQL.
+	 *
+	 * See: https://www.sqlite.org/lang_expr.html#literal_values_constants_
+	 *
+	 * Although sparsely documented, this applies to backtick and double quoted
+	 * string constants as well, so only the quote character needs to be escaped.
+	 *
+	 * For more details, see the grammar for SQLite table and column names:
+	 *
+	 *   - https://github.com/sqlite/sqlite/blob/873fc5dff2a781251f2c9bd2c791a5fac45b7a2b/src/tokenize.c#L395-L419
+	 *   - https://github.com/sqlite/sqlite/blob/873fc5dff2a781251f2c9bd2c791a5fac45b7a2b/src/parse.y#L321-L338
+	 *
+	 * ---
+	 *
+	 * We use backtick quotes instead of the SQL standard double quotes, due to
+	 * an SQLite quirk causing double-quoted strings to be accepted as literals:
+	 *
+	 *   This misfeature means that a misspelled double-quoted identifier will
+	 *   be interpreted as a string literal, rather than generating an error.
+	 *
+	 * See: https://www.sqlite.org/quirks.html#double_quoted_string_literals_are_accepted
+	 *
+	 * @param  string $unquoted_identifier The unquoted identifier value.
+	 * @return string                      The quoted identifier value.
+	 */
+	public function quote_identifier( string $unquoted_identifier ): string {
+		return '`' . str_replace( '`', '``', $unquoted_identifier ) . '`';
+	}
+
 	/**
 	 * Get the PDO object.
 	 *

wp-includes/sqlite-ast/class-wp-sqlite-driver.php

@@ -3525,13 +3525,11 @@ private function unquote_sqlite_identifier( string $quoted_identifier ): string
 	/**
 	 * Quote an SQLite identifier.
 	 *
-	 * Wrap the identifier in backticks and escape backtick values within.
-	 *
 	 * @param  string $unquoted_identifier The unquoted identifier value.
 	 * @return string                      The quoted identifier value.
 	 */
 	private function quote_sqlite_identifier( string $unquoted_identifier ): string {
-		return '`' . str_replace( '`', '``', $unquoted_identifier ) . '`';
+		return $this->connection->quote_identifier( $unquoted_identifier );
 	}
 
 

wp-includes/sqlite-ast/class-wp-sqlite-information-schema-reconstructor.php

@@ -23,6 +23,13 @@ class WP_SQLite_Information_Schema_Reconstructor {
 	 */
 	private $driver;
 
+	/**
+	 * An instance of the SQLite connection.
+	 *
+	 * @var WP_SQLite_Connection
+	 */
+	private $connection;
+
 	/**
 	 * A service for managing MySQL INFORMATION_SCHEMA tables in SQLite.
 	 *
@@ -41,6 +48,7 @@ public function __construct(
 		WP_SQLite_Information_Schema_Builder $schema_builder
 	) {
 		$this->driver         = $driver;
+		$this->connection     = $driver->get_connection();
 		$this->schema_builder = $schema_builder;
 	}
 
@@ -78,7 +86,7 @@ public function ensure_correct_information_schema(): void {
 		// Remove information schema records for tables that don't exist.
 		foreach ( $information_schema_tables as $table ) {
 			if ( ! in_array( $table, $sqlite_tables, true ) ) {
-				$sql = sprintf( 'DROP TABLE %s', $this->quote_sqlite_identifier( $table ) );
+				$sql = sprintf( 'DROP TABLE %s', $this->connection->quote_identifier( $table ) ); // TODO: mysql quote
 				$ast = $this->driver->create_parser( $sql )->parse();
 				if ( null === $ast ) {
 					throw new WP_SQLite_Driver_Exception( $this->driver, 'Failed to parse the MySQL query.' );
@@ -124,7 +132,7 @@ private function get_information_schema_table_names(): array {
 		return $this->driver->execute_sqlite_query(
 			sprintf(
 				'SELECT table_name FROM %s ORDER BY table_name',
-				$this->quote_sqlite_identifier( $tables_table )
+				$this->connection->quote_identifier( $tables_table )
 			)
 		)->fetchAll( PDO::FETCH_COLUMN );
 	}
@@ -212,7 +220,7 @@ private function generate_create_table_statement( string $table_name ): string {
 		$columns = $this->driver->execute_sqlite_query(
 			sprintf(
 				'PRAGMA table_xinfo(%s)',
-				$this->quote_sqlite_identifier( $table_name )
+				$this->connection->quote_identifier( $table_name )
 			)
 		)->fetchAll( PDO::FETCH_ASSOC );
 
@@ -244,7 +252,7 @@ private function generate_create_table_statement( string $table_name ): string {
 		if ( count( $pk_columns ) > 0 ) {
 			$quoted_pk_columns = array();
 			foreach ( $pk_columns as $pk_column ) {
-				$quoted_pk_columns[] = $this->quote_sqlite_identifier( $pk_column );
+				$quoted_pk_columns[] = $this->connection->quote_identifier( $pk_column );
 			}
 			$definitions[] = sprintf( 'PRIMARY KEY (%s)', implode( ', ', $quoted_pk_columns ) );
 		}
@@ -253,7 +261,7 @@ private function generate_create_table_statement( string $table_name ): string {
 		$keys = $this->driver->execute_sqlite_query(
 			sprintf(
 				'PRAGMA index_list(%s)',
-				$this->quote_sqlite_identifier( $table_name )
+				$this->connection->quote_identifier( $table_name )
 			)
 		)->fetchAll( PDO::FETCH_ASSOC );
 
@@ -268,7 +276,7 @@ private function generate_create_table_statement( string $table_name ): string {
 
 		return sprintf(
 			"CREATE TABLE %s (\n  %s\n)",
-			$this->quote_sqlite_identifier( $table_name ),
+			$this->connection->quote_identifier( $table_name ),
 			implode( ",\n  ", $definitions )
 		);
 	}
@@ -284,7 +292,7 @@ private function generate_create_table_statement( string $table_name ): string {
 	 */
 	private function generate_column_definition( string $table_name, array $column_info ): string {
 		$definition   = array();
-		$definition[] = $this->quote_sqlite_identifier( $column_info['name'] );
+		$definition[] = $this->connection->quote_identifier( $column_info['name'] );
 
 		// Data type.
 		$mysql_type = $this->get_cached_mysql_data_type( $table_name, $column_info['name'] );
@@ -379,14 +387,14 @@ private function generate_key_definition( string $table_name, array $key_info, a
 		 * the generated MySQL definition, they follow implicit MySQL naming.
 		 */
 		if ( ! str_starts_with( $name, 'sqlite_autoindex_' ) ) {
-			$definition[] = $this->quote_sqlite_identifier( $name );
+			$definition[] = $this->connection->quote_identifier( $name );
 		}
 
 		// Key columns.
 		$key_columns = $this->driver->execute_sqlite_query(
 			sprintf(
 				'PRAGMA index_info(%s)',
-				$this->quote_sqlite_identifier( $key_info['name'] )
+				$this->connection->quote_identifier( $key_info['name'] )
 			)
 		)->fetchAll( PDO::FETCH_ASSOC );
 		$cols        = array();
@@ -423,11 +431,11 @@ private function generate_key_definition( string $table_name, array $key_info, a
 			) {
 				$cols[] = sprintf(
 					'%s(%d)',
-					$this->quote_sqlite_identifier( $column['name'] ),
+					$this->connection->quote_identifier( $column['name'] ),
 					min( $column_length ?? $max_prefix_length, $max_prefix_length )
 				);
 			} else {
-				$cols[] = $this->quote_sqlite_identifier( $column['name'] );
+				$cols[] = $this->connection->quote_identifier( $column['name'] );
 			}
 		}
 
@@ -640,18 +648,6 @@ private function escape_mysql_string_literal( string $literal ): string {
 		return "'" . addcslashes( $literal, "\0\n\r'\"\Z" ) . "'";
 	}
 
-	/**
-	 * Quote an SQLite identifier.
-	 *
-	 * Wrap the identifier in backticks and escape backtick values within.
-	 *
-	 * @param  string $unquoted_identifier The unquoted identifier value.
-	 * @return string                      The quoted identifier value.
-	 */
-	private function quote_sqlite_identifier( string $unquoted_identifier ): string {
-		return '`' . str_replace( '`', '``', $unquoted_identifier ) . '`';
-	}
-
 	/**
 	 * Unquote a quoted MySQL identifier.
 	 *