云策 WordPress 开发者社区

函数文档

esc_sql()

查看官方原文 ↗
💡 云策文档标注

概述

esc_sql() 函数用于转义数据以在 MySQL 查询中使用，通常建议优先使用 wpdb::prepare() 进行查询准备。该函数仅转义在 SQL 字符串引号内的值，不适用于未加引号的数值、字段名或 SQL 关键字。

关键要点

  • esc_sql() 转义数据用于 MySQL 查询，但主要用于字符串值在引号内的情况。
  • 从 WordPress 4.8.3 起，'%' 字符会被替换为占位符字符串，以防止某些 SQL 注入攻击，这可能影响代码的预期行为。
  • 函数参数 $data 可以是字符串或数组，返回转义后的相同类型数据。
  • 使用 esc_sql() 时需谨慎，因为它不转义未加引号的数值、字段名或 SQL 关键字，可能导致 SQL 注入漏洞。
  • 推荐使用 $wpdb->prepare() 替代，因为它能纠正一些常见的格式化错误。
  • esc_sql() 原是 $wpdb->escape() 的别名，但后者现已弃用。

代码示例

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

注意事项

esc_sql() 仅适用于值在 SQL 引号内的情况（如 field = '{$escaped_value}'），否则代码仍易受 SQL 注入攻击。例如，ORDER BY {$escaped_value} 是脆弱的，因为转义值未在查询中用引号包围。

📄 原文内容

Escapes data for use in a MySQL query.

Description

Usually you should prepare queries using wpdb::prepare().
Sometimes, spot-escaping is required or useful. One example is preparing an array for use in an IN clause.

NOTE: Since 4.8.3, ‘%’ characters will be replaced with a placeholder string, this prevents certain SQLi attacks from taking place. This change in behavior may cause issues for code that expects the return value of esc_sql() to be usable for other purposes.

Parameters

$datastring|arrayrequired
Unescaped data.

Return

string|array Escaped data, in the same type as supplied.

More Information

  • Be careful in using this function correctly. It will only escape values to be used in strings in the query. That is, it only provides escaping for values that will be within quotes in the SQL (as in field = '{$escaped_value}'). If your value is not going to be within quotes, your code will still be vulnerable to SQL injection. For example, this is vulnerable, because the escaped value is not surrounded by quotes in the SQL query: ORDER BY {$escaped_value}. As such, this function does not escape unquoted numeric values, field names, or SQL keywords.
  • $wpdb->prepare() is generally preferred as it corrects some common formatting errors.
  • This function was formerly just an alias for $wpdb->escape(), but that function has now been deprecated.

Source

function esc_sql( $data ) {
	global $wpdb;
	return $wpdb->_escape( $data );
}

View all references View on Trac View on GitHub

Uses Description
wpdb::_escape()wp-includes/class-wpdb.php

Escapes data. Works on arrays.
Used by Description
WP_User_Query::parse_orderby()wp-includes/class-wp-user-query.php

Parses and sanitizes ‘orderby’ keys passed to the user query.
WP_Comment_Query::parse_orderby()wp-includes/class-wp-comment-query.php

Parse and sanitize ‘orderby’ keys passed to the comment query.
WP_Date_Query::get_sql_for_clause()wp-includes/class-wp-date-query.php

Turns a first-order date query into SQL for a WHERE clause.
WP_Query::get_posts()wp-includes/class-wp-query.php

Retrieves an array of posts based on query variables.
_pad_term_counts()wp-includes/taxonomy.php

Adds count of children to parent count.
_update_post_term_count()wp-includes/taxonomy.php

Updates term count based on object types of the current taxonomy.
WP_Date_Query::__construct()wp-includes/class-wp-date-query.php

Constructor.
wp_load_alloptions()wp-includes/option.php

Loads and caches all autoloaded options, if available or all options.
get_page_by_path()wp-includes/post.php

Retrieves a page given its path.
get_page_by_title()wp-includes/deprecated.php

Retrieves a page given its title.
redirect_guess_404_permalink()wp-includes/canonical.php

Attempts to guess the correct URL for a 404 request based on query vars.

Show 6 moreShow less

Changelog

Version Description
2.8.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    J.D. Grimes


    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

    It should be noted that this function will only escape values to be used in strings in the query. That is, it only provides escaping for values that will be within quotes in the SQL (as in field = '{$escaped_value}'). If your value is not going to be within quotes, your code will still be vulnerable to SQL injection. For example, this is vulnerable, because the escaped value is not surrounded by quotes in the SQL query: ORDER BY {$escaped_value}. As such, this function does not escape unquoted numeric values, field names, or SQL keywords..