mysql_result

mysql_query

Last updated: Fri, 03 Jul 2009

mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Escapes special characters in a string for use in a SQL statement

Description

string mysql_real_escape_string ( string $unescaped_string [, resource $link_identifier ] )

Escapes special characters in the unescaped_string , taking into account the current character set of the connection so that it is safe to place it in a mysql_query(). If binary data is to be inserted, this function must be used.

mysql_real_escape_string() calls MySQL's library function mysql_real_escape_string, which prepends backslashes to the following characters: \x00, \n, \r, \, ', " and \x1a.

This function must always (with few exceptions) be used to make data safe before sending a query to MySQL.

Parameters

unescaped_string: The string that is to be escaped.
link_identifier: The MySQL connection. If the link identifier is not specified, the last link opened by mysql_connect() is assumed. If no such link is found, it will try to create one as if mysql_connect() was called with no arguments. If by chance no connection is found or established, an E_WARNING level error is generated.

Return Values

Returns the escaped string, or FALSE on error.

Examples

Example #1 Simple mysql_real_escape_string() example


<?php
// Connect
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
    OR die(mysql_error());

// Query
$query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
            mysql_real_escape_string($user),
            mysql_real_escape_string($password));
?>

Example #2 An example SQL Injection Attack


<?php
// Query database to check if there are any matching users
$query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
mysql_query($query);

// We didn't check $_POST['password'], it could be anything the user wanted! For example:
$_POST['username'] = 'aidan';
$_POST['password'] = "' OR ''='";

// This means the query sent to MySQL would be:
echo $query;
?>

The query sent to MySQL:

SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

This would allow anyone to log in without a valid password.

Notes

Note: A MySQL connection is required before using mysql_real_escape_string() otherwise an error of level E_WARNING is generated, and FALSE is returned. If link_identifier isn't defined, the last MySQL connection is used.

Note: If magic_quotes_gpc is enabled, first apply stripslashes() to the data. Using this function on data which has already been escaped will escape the data twice.

Note: If this function is not used to escape data, the query is vulnerable to SQL Injection Attacks.

Note: mysql_real_escape_string() does not escape % and _. These are wildcards in MySQL if combined with LIKE, GRANT, or REVOKE.


I always use this function so I don't have to retype over and over the mysql_real_escape_string function.





<?php


function safe($value){


   return mysql_real_escape_string($value);


}


?>





Then, when I am using my code, I simply use:





<?php


$name = safe($_POST["name"]);


$password = safe($_POST["password"]);


?>

kendsnyder at gmail dot com
25-Mar-2009 10:07


<?php



// Here is a simple named binding function for queries that makes SQL more readable:

// $sql = "SELECT * FROM users WHERE user = :user AND password = :password";

// mysql_bind($sql, array('user' => $user, 'password' => $password));

// mysql_query($sql);



function mysql_bind(&$sql, $vals) {

    foreach ($vals as $name => $val) {

        $sql = str_replace(":$name", "'" . mysql_real_escape_string($val) . "'", $sql);

    }

}



?>

Bastiaan Welmers
24-Mar-2008 08:46


This function won't help you when inserting binary data, to me it will get mallformed into the database. Probably UTF-8 combinations will be translated by this function or somewhere else when inserting data when running mysql in UTF-8 mode.



A better way to insert binary data is to transfer it to hexadecimal notation like this example:



<?php

$string = $_REQUEST['string'];

$binary = file_get_contents($_FILE['file']['tmp_name']);



$string = mysql_real_escape_string($string);

$binary_hex = bin2hex($binary);



$query = "INSERT INTO `table` (`key`, `string`, `binary`, `other`) VALUES (NULL, '$string', 0x$binary_hex, '$other')";



?>

Anonymous
03-Mar-2008 07:57


My escape function:





Automatically adds quotes (unless $quotes is false), but only for strings. Null values are converted to mysql keyword "null", booleans are converted to 1 or 0, and numbers are left alone. Also can escape a single variable or recursively escape an array of unlimited depth.





<?php


function db_escape($values, $quotes = true) {


    if (is_array($values)) {


        foreach ($values as $key => $value) {


            $values[$key] = db_escape($value, $quotes);


        }


    }


    else if ($values === null) {


        $values = 'NULL';


    }


    else if (is_bool($values)) {


        $values = $values ? 1 : 0;


    }


    else if (!is_numeric($values)) {


        $values = mysql_real_escape_string($values);


        if ($quotes) {


            $values = '"' . $values . '"';


        }


    }


    return $values;


}


?>

matthijs at yourmediafactory dot com
27-Dec-2007 10:49


In response to Michael D - DigitalGemstones.com: 



Check the example again: sprintf(%d) already does the int conversion for you, so it's both perfectly save as well as more elegant than manually casting.

user at NOSPAM dot example dot com
28-Aug-2007 02:16


if you're doing a mysql wildcard query with


LIKE, GRANT, or REVOKE


you may use addcslashes to escape the string:





<?php


$param = mysql_real_escape_string($param);


$param = addcslashes($param, '%_');


?>

brian dot folts at gmail dot com
06-Sep-2006 06:25


mysql_real_escape_string is a bit annoying when you need to do it over an array.





<?php


function mysql_real_escape_array($t){


    return array_map("mysql_real_escape_string",$t);


}


?>





this one just mysql_real_escape's the whole array.





ex) <?php $_POST=mysql_real_escape_array($_POST); ?>





and then you dont have to worry about forgetting to do this.

kael dot shipman at DONTSPAMIT! dot gmail dot com
18-Jul-2006 10:19


It seems to me that you could avoid many hassels by loading valid database values into an array at the beginning of the script, then instead of using user input to query the database directly, use it to query the array you've created. For example:



<?php

//you still have to query safely, so always use cleanup functions like eric256's

$categories = sql_query("select catName from categories where pageID = ?",$_GET['pageID']);

while ($cts = @mysql_fetch_row($categories)) {

 //making $cts both the name and the value of the array variable makes it easier to check for in the future.

 //obviously, this naming system wouldn't work for a multidimensional array

 $cat_ar[$cts[0]] = $cts[0];

}

...



//user selects sorting criteria

//this would be from a query string like '?cats[]=cha&cats[]=fah&cats[]=lah&cats[]=badValue...', etc.

$cats = $_GET['cats'];



//verify that values exist in database before building sorting query

foreach($cats as $c) {

 if ($cat_ar[$c]) { //instead of in_array(); maybe I'm just lazy... (see above note)

  $cats1[] = "'".mysql_real_escape_string($c)."'";

 }

}

$cats = $cats1;

//$cats now contains the filtered and escaped values of the query string



$cat_query = '&& (category_name = \''.implode(' || category_name = \'',$cats).'\')';

//build a sql query insert

//$cat_query is now "&& (category_name = 'cha' || category_name = 'fah' || category_name = 'lah')" - badValue has been removed

//since all values have already been verified and escaped, you can simply use them in a query

//however, since $pageID hasn't been cleaned for this query, you still have to use your cleaning function

$items = sql_query("SELECT * FROM items i, categories c WHERE i.catID = c.catID && pageID = ? $cat_query", $pageID);

nicolas
30-May-2006 10:38


Note that mysql_real_escape_string doesn't prepend backslashes to \x00, \n, \r, and and \x1a as mentionned in the documentation, but actually replaces the character with a MySQL acceptable representation for queries (e.g. \n is replaced with the '\n' litteral). (\, ', and " are escaped as documented) This doesn't change how you should use this function, but I think it's good to know.

add a note