WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

wpdb::prepare() WP 1.0

Позволяет писать SQL запрос с очисткой передаваемых в него параметров.

Ищем WP-разработчика! Фулл-тайм, удаленка, хорошая зарплата, соц. пакет. Подробности.
Компания Boosta.

В строке запроса вместо передаваемого параметра нужно использовать плейсхолдер: %s, %d или %f. Также для каждого из плейсхолдеров указывается PHP переменная, которая заменит плейсхолдер. При замене переменная будет очищена. Синтаксис похожий на sprintf().

С WP 3.5 обязательно должны быть переданы минимум 2 параметра: запрос и значение переменной, иначе будет php ошибка (User Notice).

Кавычки для плейсхолдеров %s и '%s'.

Плейсхолдеры могут быть в кавычках или без них: WHERE field = %s или WHERE field = '%s'. Кавычки принято не ставить.

echo $wpdb->prepare( "foo = %s", 'a' );   // foo = 'a'
echo $wpdb->prepare( "foo = '%s'", 'a' ); // foo = 'a'
Параметр для каждого плейсхолдера.

Параметр должен быть указан для каждого плейсхолдера.

echo $wpdb->prepare( 'foo = %s AND bar = %s', 'a' );
echo $wpdb->prepare( 'foo = %1$s AND bar = %1$s', 'a' );
// в обоих случаях увидим ошибку:
// User Notice: wpdb::prepare was called incorrectly.
// The query does not contain the correct number of placeholders (2)
// for the number of arguments passed (1).
Порядковые плейсхолдеры %1$s.

Для совместимости со старыми версиями: порядковые плейсхолдеры (например, %1$s, %5s) обрабатываются иначе - им не добавляются кавычки, поэтому они должны быть снабжены правильными кавычками в строке запроса.

echo $wpdb->prepare( 'foo = %1$s', 'a"a' );   // foo = a\"a
echo $wpdb->prepare( 'foo = "%1$s"', 'a"a' ); // foo = "a\"a"
echo $wpdb->prepare( 'foo = %1s', 'a"a' );    // foo = a\"a
echo $wpdb->prepare( 'foo = %s', 'a"a' );     // foo = 'a\"a'
Знак %

Знак % в строке запроса, который не относится к плейсхолдеру нужно записывать так %%.

echo $wpdb->prepare( "%foo AND id = %d", 2 ); // User Notice: wpdb::prepare was called incorrectly.
echo $wpdb->prepare( "%%foo AND id = %d", 2 ); // %foo AND id = 2
% в LIKE синтаксисе

Подстановочные знаки процента % в LIKE синтаксисе должны указываться через параметр подстановки содержащий полную LIKE строку, а не напрямую в запросе. Также смотрите wpdb::esc_like().

$like = '%'. $wpdb->esc_like( "bar's" ) .'%end';
echo $wpdb->prepare( "foo LIKE %s", $like ); // foo LIKE '{a0d1d}bar\'s{a0d1d}end'

SQL инъекция

В SQL есть такое понятие как «инъекция» (внедрение в запрос SQL кода). Cделать его можно, когда в запрос передаются динамические данные. Например, в запрос передаётся значение input поля, в это поле можно указать данные, которые в итоге станут частью SQL запроса. Так можно внедриться в запрос и что-нибудь испортить или просто нарушить код самого запроса. Выглядит это так:

$sql = "SELECT * FROM table WHERE id = '$var'";

Теперь, если var = 2' AND id = (DROP TABLE table2) то в результате запрос получиться такой:

SELECT * FROM table WHERE id = '2' AND id = (DROP TABLE table2)

Таким образом можно внедриться в сам запрос и изменить его. Чтобы этого не произошло запросы с передаваемыми в них переменными нужно обрабатывать методом prepare():

$sql = $wpdb->prepare( "SELECT * FROM table WHERE id = %s", $var );

esc_sql()

Кроме метода $wpdb->prepare() запрос можно очистить функцией esc_sql(). Но «prepare» предпочтительнее, потому что исправляет некоторые ошибки форматирования.

$name   = esc_sql( $name );
$status = esc_sql( $status );

$wpdb->get_var( "SELECT something FROM table WHERE foo = '$name' and status = '$status'" );

ВАЖНО! После esc_sql() очищенную строку можно использовать только внутри кавычек '' или "". Т.е. правильно писать field = '$value', а не field = $value, где $value = esc_sql( $value );

{} Это метод класса: wpdb{}

Работает на основе: wpdb::add_placeholder_escape()

Хуков нет.

Возвращает

Строку|null. Sanitized query string, if there is a query to prepare.

Использование

global $wpdb;
$wpdb->prepare( $query, ...$args );
$query(строка) (обязательный)

Строка запроса. В нем можно использовать заменители:

  • %d - число
  • %s - строка
  • %f - дробное число (число с плавающей точкой, с версии 3.3).
...$args(строка/число/массив)

Переменные, которые будут использованы для замены плейсхолдеров %s %d %f в строке запроса.

Эти переменные можно указать через запятую (как дополнительные параметры функции) или в массиве:

  • $wpdb->prepare( 'query', $param1, $param2 )
  • $wpdb->prepare( 'query', [ $param1, $param2 ] ).

Примеры

#2. Демонстрация работы

$wpdb->prepare(
	"SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s",
	[ 'foo', 1337, '%bar' ]
);

$wpdb->prepare(
	"SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo'
);

#2. Добавим произвольное поле к посту 10

Из примера видно, что с prepare() нет необходимости заботиться об экранировании кавычек и прочего, что может навредить запросу.

$metakey   = "'крах' БД";
$metavalue = "WordPress может 'сломать' Базу Данных если не экранировать запрос.";

$wpdb->query(
	$wpdb->prepare(
		"INSERT INTO $wpdb->postmeta ( post_id, meta_key, meta_value ) VALUES ( %d, %s, %s )",
		10,
		$metakey,
		$metavalue
  )
);

#3. Передача параметров в виде массива

Это такой же пример, только тут все переменные передаются во втором параметре в виде массива.

Передавать параметры в виде массива, может быть полезно, когда мы заранее не знаем количество аргументов, которые нужно будет передать.

$metakey = "'крах' БД";
$metavalue = "WordPress может 'сломать' Базу Данных если не экранировать запрос.";

$wpdb->query(
	$wpdb->prepare(
		"INSERT INTO $wpdb->postmeta ( post_id, meta_key, meta_value ) VALUES ( %d, %s, %s )",
		array(
			10,
			$metakey,
			$metavalue
		)
  )
);

Список изменений

С версии 2.3.0 Введена.
С версии 5.3.0 Formalized the existing and already documented ...$args parameter by updating the function signature. The second parameter was changed from $args to ...$args.

Код wpdb::prepare() WP 5.8.2

public function prepare( $query, ...$args ) {
	if ( is_null( $query ) ) {
		return;
	}

	// This is not meant to be foolproof -- but it will catch obviously incorrect usage.
	if ( strpos( $query, '%' ) === false ) {
		wp_load_translations_early();
		_doing_it_wrong(
			'wpdb::prepare',
			sprintf(
				/* translators: %s: wpdb::prepare() */
				__( 'The query argument of %s must have a placeholder.' ),
				'wpdb::prepare()'
			),
			'3.9.0'
		);
	}

	// If args were passed as an array (as in vsprintf), move them up.
	$passed_as_array = false;
	if ( is_array( $args[0] ) && count( $args ) === 1 ) {
		$passed_as_array = true;
		$args            = $args[0];
	}

	foreach ( $args as $arg ) {
		if ( ! is_scalar( $arg ) && ! is_null( $arg ) ) {
			wp_load_translations_early();
			_doing_it_wrong(
				'wpdb::prepare',
				sprintf(
					/* translators: %s: Value type. */
					__( 'Unsupported value type (%s).' ),
					gettype( $arg )
				),
				'4.8.2'
			);
		}
	}

	/*
	 * Specify the formatting allowed in a placeholder. The following are allowed:
	 *
	 * - Sign specifier. eg, $+d
	 * - Numbered placeholders. eg, %1$s
	 * - Padding specifier, including custom padding characters. eg, %05s, %'#5s
	 * - Alignment specifier. eg, %05-s
	 * - Precision specifier. eg, %.2f
	 */
	$allowed_format = '(?:[1-9][0-9]*[$])?[-+0-9]*(?: |0|\'.)?[-+0-9]*(?:\.[0-9]+)?';

	/*
	 * If a %s placeholder already has quotes around it, removing the existing quotes and re-inserting them
	 * ensures the quotes are consistent.
	 *
	 * For backward compatibility, this is only applied to %s, and not to placeholders like %1$s, which are frequently
	 * used in the middle of longer strings, or as table name placeholders.
	 */
	$query = str_replace( "'%s'", '%s', $query ); // Strip any existing single quotes.
	$query = str_replace( '"%s"', '%s', $query ); // Strip any existing double quotes.
	$query = preg_replace( '/(?<!%)%s/', "'%s'", $query ); // Quote the strings, avoiding escaped strings like %%s.

	$query = preg_replace( "/(?<!%)(%($allowed_format)?f)/", '%\\2F', $query ); // Force floats to be locale-unaware.

	$query = preg_replace( "/%(?:%|$|(?!($allowed_format)?[sdF]))/", '%%\\1', $query ); // Escape any unescaped percents.

	// Count the number of valid placeholders in the query.
	$placeholders = preg_match_all( "/(^|[^%]|(%%)+)%($allowed_format)?[sdF]/", $query, $matches );

	$args_count = count( $args );

	if ( $args_count !== $placeholders ) {
		if ( 1 === $placeholders && $passed_as_array ) {
			// If the passed query only expected one argument, but the wrong number of arguments were sent as an array, bail.
			wp_load_translations_early();
			_doing_it_wrong(
				'wpdb::prepare',
				__( 'The query only expected one placeholder, but an array of multiple placeholders was sent.' ),
				'4.9.0'
			);

			return;
		} else {
			/*
			 * If we don't have the right number of placeholders, but they were passed as individual arguments,
			 * or we were expecting multiple arguments in an array, throw a warning.
			 */
			wp_load_translations_early();
			_doing_it_wrong(
				'wpdb::prepare',
				sprintf(
					/* translators: 1: Number of placeholders, 2: Number of arguments passed. */
					__( 'The query does not contain the correct number of placeholders (%1$d) for the number of arguments passed (%2$d).' ),
					$placeholders,
					$args_count
				),
				'4.8.3'
			);

			/*
			 * If we don't have enough arguments to match the placeholders,
			 * return an empty string to avoid a fatal error on PHP 8.
			 */
			if ( $args_count < $placeholders ) {
				$max_numbered_placeholder = ! empty( $matches[3] ) ? max( array_map( 'intval', $matches[3] ) ) : 0;

				if ( ! $max_numbered_placeholder || $args_count < $max_numbered_placeholder ) {
					return '';
				}
			}
		}
	}

	array_walk( $args, array( $this, 'escape_by_ref' ) );
	$query = vsprintf( $query, $args );

	return $this->add_placeholder_escape( $query );
}

wpdb

Комментариев нет
    Войти