mysql_real_escape_string

Escapes special characters in a string for use in an SQL statement

&mysql.alternative.note;

- `mysqli_real_escape_string`
- `PDO::quote`

&reftitle.description; `string` `mysql_real_escape_string` `string` `unescaped_string` `resource` `link_identifier` NULL

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.

### Security: the default character set

The character set must be set either at the server level, or with the API function `mysql_set_charset` for it to affect `mysql_real_escape_string`. See the concepts section on character sets for more information.

&reftitle.parameters;

`unescaped_string`

- The string that is to be escaped.

&mysql.linkid.description;
&reftitle.returnvalues;

Returns the escaped string, or &false; on error.

&reftitle.errors;

Executing this function without a MySQL connection present will also emit `E_WARNING` level PHP errors. Only execute this function with a valid MySQL connection present.

&reftitle.examples;

### 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));
    ?>

### `mysql_real_escape_string` requires a connection example

This example demonstrates what happens if a MySQL connection is not present when calling this function.

    <?php
    // We have not connected to MySQL

    $lastname  = "O'Reilly";
    $_lastname = mysql_real_escape_string($lastname);

    $query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

    var_dump($_lastname);
    var_dump($query);
    ?>

&example.outputs.similar;

    Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
    Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

    bool(false)
    string(41) "SELECT * FROM actors WHERE last_name = ''"

### An example SQL Injection Attack

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

    // 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);

    // 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.

&reftitle.notes;

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.

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

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

&reftitle.seealso;

- `mysql_set_charset`
- `mysql_client_encoding`