prepare() for every value and %i for every identifier. * WordPress's own connection is the only one: no credentials are read and no second connection * is opened. * * There are no raw mysqli calls. Two kinds of statement need care, and both still go through $wpdb: * * 1. batch(): exporting a table reads it in batches of rows, each one a buffered * $wpdb->get_results() whose memory Table_Exporter bounds: large values are left out of the batch * and fetched separately in pieces, and batches with large columns are kept short. * 2. raw(): running the SQL a backup carries (its CREATE TABLE/VIEW/TRIGGER definitions and its * INSERT chunks) and the session statements that must share their connection. $wpdb->query() * refuses any statement holding bytes that are invalid in the column's character set, and sites * store such bytes (binary data in text columns, latin1 tables), so for these statements only, * its $check_current_query is turned off, which is what wpdb::insert() and replace() do for data * they have already checked. It applies to one statement and wpdb turns it back on. These * statements are never built from request input: definitions pass Ddl_Guard and * Ddl_Normalizer, and chunks pass Insert_Transformer, before they get here. * * literal() writes values into that SQL. It uses esc_sql() and then removes the placeholders * esc_sql() puts in place of '%', because the text goes into a backup file, not into $wpdb->query() * (which is what removes them). * * @package AccessNow\Replica */ namespace AccessNow\Replica\Db; defined( 'ABSPATH' ) || exit; // Exception messages are plain text: they are escaped where shown (esc_html() in PHP, textContent in admin.js). // phpcs:disable WordPress.Security.EscapeOutput.ExceptionNotEscaped // Every statement handed to $wpdb below was built by $wpdb->prepare() in this class, or is a fixed // statement with no values; callers never pass values into the SQL text. // phpcs:disable WordPress.DB.PreparedSQL.NotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.DirectDatabaseQuery.SchemaChange /** * Database access. */ final class Connection { /** * Use Connection::wp(). */ private function __construct() { } /** * WordPress's connection. * * @throws Db_Exception When the site does not use mysqli (e.g. SQLite drop-in). */ public static function wp() { global $wpdb; if ( ! isset( $wpdb->dbh ) || ! ( $wpdb->dbh instanceof \mysqli ) ) { throw new Db_Exception( 'This site does not use a MySQL/MariaDB connection that Site Replica can read (a database drop-in may be installed).' ); } return new self(); } /** * Runs a statement through $wpdb. * * @param string $sql SQL with $wpdb->prepare() placeholders (%s, %d, %i), or none. * @param mixed ...$args Values for the placeholders. * @return int|bool Rows affected, or true. * @throws Db_Exception On error. */ public function query( $sql, ...$args ) { global $wpdb; $quiet = $wpdb->suppress_errors( true ); if ( $args ) { $prepared = $wpdb->prepare( $sql, ...$args ); if ( ! is_string( $prepared ) || '' === $prepared ) { $wpdb->suppress_errors( $quiet ); throw new Db_Exception( 'A database statement could not be prepared.', 0, $sql ); } $result = $wpdb->query( $prepared ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- Built by $wpdb->prepare() just above; callers pass values only as arguments. } else { // A fixed statement: callers pass every value as an argument, never in $sql. $result = $wpdb->query( $sql ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter } $wpdb->suppress_errors( $quiet ); $this->check_error( $sql ); return $result; } /** * All rows as associative arrays. * * @param string $sql SQL with placeholders, or none. * @param mixed ...$args Values. * @return array[] * @throws Db_Exception On error. */ public function rows( $sql, ...$args ) { global $wpdb; $quiet = $wpdb->suppress_errors( true ); if ( $args ) { $prepared = $wpdb->prepare( $sql, ...$args ); if ( ! is_string( $prepared ) || '' === $prepared ) { $wpdb->suppress_errors( $quiet ); throw new Db_Exception( 'A database statement could not be prepared.', 0, $sql ); } $result = $wpdb->get_results( $prepared, ARRAY_A ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- Built by $wpdb->prepare() just above; callers pass values only as arguments. } else { // A fixed statement: callers pass every value as an argument, never in $sql. $result = $wpdb->get_results( $sql, ARRAY_A ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter } $wpdb->suppress_errors( $quiet ); $this->check_error( $sql ); return (array) $result; } /** * First column of the first row. * * @param string $sql SQL with placeholders, or none. * @param mixed ...$args Values. * @return string|null * @throws Db_Exception On error. */ public function value( $sql, ...$args ) { global $wpdb; $quiet = $wpdb->suppress_errors( true ); if ( $args ) { $prepared = $wpdb->prepare( $sql, ...$args ); if ( ! is_string( $prepared ) || '' === $prepared ) { $wpdb->suppress_errors( $quiet ); throw new Db_Exception( 'A database statement could not be prepared.', 0, $sql ); } $result = $wpdb->get_var( $prepared ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- Built by $wpdb->prepare() just above; callers pass values only as arguments. } else { // A fixed statement: callers pass every value as an argument, never in $sql. $result = $wpdb->get_var( $sql ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter } $wpdb->suppress_errors( $quiet ); $this->check_error( $sql ); return $result; } /** * Prepares a statement or fragment with $wpdb->prepare() (%s, %d, %i). * * @param string $sql SQL with placeholders. * @param array $args Values. * @return string */ public static function prepare( $sql, array $args ) { global $wpdb; return $args ? (string) $wpdb->prepare( $sql, ...$args ) : $sql; } /** * Reads one batch of rows, as numeric arrays, and frees $wpdb's copy of the result. * * @param string $sql SQL with placeholders. * @param array $args Placeholder values. * @return array> * @throws Db_Exception On error. */ public function batch( $sql, array $args = array() ) { global $wpdb; $quiet = $wpdb->suppress_errors( true ); $prepared = self::prepare( $sql, $args ); if ( '' === $prepared ) { $wpdb->suppress_errors( $quiet ); throw new Db_Exception( 'A database statement could not be prepared.', 0, $sql ); } $rows = $wpdb->get_results( $prepared, ARRAY_N ); // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- Built by $wpdb->prepare() just above; callers pass values only as arguments. $wpdb->suppress_errors( $quiet ); $this->check_error( $sql ); $wpdb->flush(); // A batch can be megabytes: don't keep a second copy in $wpdb->last_result. return is_array( $rows ) ? $rows : array(); } /** * Runs SQL from a backup, or a session statement (see the file comment). * * @param string $sql SQL. * @return int|bool Rows affected, or true. * @throws Db_Exception On error. */ public function raw( $sql ) { global $wpdb; $quiet = $wpdb->suppress_errors( true ); // Keep bytes that are invalid in the column's charset, as the site stored them. wpdb turns // this back on after the one statement. $wpdb->check_current_query = false; $result = $wpdb->query( $sql ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- SQL from the backup itself, checked by Ddl_Guard, Ddl_Normalizer and Insert_Transformer; see the file comment. $wpdb->check_current_query = true; $wpdb->suppress_errors( $quiet ); $this->check_error( $sql ); return $result; } /** * A string literal for SQL written into a backup or read from one. * * @param string $value Raw bytes. */ public static function literal( $value ) { global $wpdb; return "'" . $wpdb->remove_placeholder_escape( esc_sql( (string) $value ) ) . "'"; } /** * Quotes an identifier, for SQL written into a backup (queries use %i). * * @param string $name Table or column name. */ public static function ident( $name ) { return '`' . str_replace( '`', '``', (string) $name ) . '`'; } /** * Server version string. */ public function server_info() { global $wpdb; return (string) $wpdb->db_server_info(); } /** * Turns the error of the $wpdb call just made into an exception. * * @param string $sql SQL (for the log). * @throws Db_Exception On error. */ private function check_error( $sql ) { global $wpdb; if ( '' !== (string) $wpdb->last_error ) { throw new Db_Exception( $wpdb->last_error, 0, $sql ); } } }