Escapa os caracteres especiais em uma string para uso em uma instrução SQL

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Escapa os caracteres especiais em uma string para uso em uma instrução SQL

Aviso

Esta extensão foi descontinuada a partir do PHP 5.5.0 e foi removida no PHP 7.0.0. Em vez disso, as extensões MySQLi ou PDO_MySQL devem ser usadas. Veja também o guia MySQL: escolhendo uma API. Alternativas a esta função incluem:

- mysqli_real_escape_string()
- PDO::quote()

### Descrição

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

Escapa caracteres especiais do parâmetro `unescaped_string`, levando em conta o conjunto de caracteres atual da conexão, de forma que seja seguro inseri-la na função mysql_query(). Se forem inseridos dados binários, esta função precisa ser usada.

mysql_real_escape_string() chama a função mysql_real_escape_string da biblioteca do MySQL, que prefixa com barras invertidas os seguintes caracteres: `\x00`, `\n`, `\r`, `\`, `'`, `"` e `\x1a`.

Esta função precisa sempre ser usada (com poucas exceções) para tornar os dados seguros antes de enviá-los em uma consulta ao MySQL.

Cuidado

# Segurança: o conjunto de caracteres padrão

O conjunto de caracteres precisa ser definido no nível do servidor ou com a função mysql_set_charset() da API para que afete a função mysql_real_escape_string(). Consulte a seção de conceitos sobre conjuntos de caracteres para mais informação.

### Parâmetros

`unescaped_string`
  A string a ser escapada.
`link_identifier`
  A conexão MySQL. Se o identificador da conexão não for especificado, a última conexão aberta por mysql_connect() será usada. Se não houver uma conexão anterior, haverá uma tentativa de criar uma como se mysql_connect() tivesse sido chamada sem argumentos. Se nenhuma conexão for encontrada ou estabelecida, um erro de nível `E_WARNING` será gerado.

### Valor Retornado

Retorna a string escapada ou `false` em caso de erro.

### Erros/Exceções

Executar esta função sem uma conexão MySQL presente emitirá um erro de nível `E_WARNING`. Esta função deve ser executada somente com uma conexão MySQL válida presente.

### Exemplos

Exemplo #1 Exemplo de mysql_real_escape_string()

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

Exemplo #2 mysql_real_escape_string() requer um exemplo de conexão

Este exemplo demonstra o que acontece se uma conexão MySQL não estiver presente ao chamar esta função.

    <?php
    // Ainda não foi feita conexão ao MySQL

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

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

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

O exemplo acima produzirá algo semelhante a:

    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 = ''"

Exemplo #3 Um exemplo de Ataque de Injeção SQL

    <?php
    // Não verificamos $_POST['password'], ela pode conter qualquer coisa que o usuário quiser! Por exemplo:
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // Consulta o banco de dados para verificar se existe algum usuário correspondente
    $query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($query);

    // Isto significa que a consulta enviada ao MySQL seria:
    echo $query;
    ?>

A consulta enviada ao MySQL:

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

Isto permitiria que qualquer pessoa fizesse login sem uma senha válida.

### Notas

> Nota: Uma conexão MySQL é requerida antes que mysql_real_escape_string() seja usada, caso contrário um erro de nível `E_WARNING` será gerado e `false` é retornado. Se `link_identifier` não estiver definido, a últimoa conexão MySQL será usada.

> Nota: Se esta função não for usada para escapar dados, a consulta ficará vulnerável a Ataques de Injeção SQL.

> Nota: mysql_real_escape_string() não escapa `%` e `_`. Estes caracteres são coringas no MySQL se combinados com `LIKE`, `GRANT` ou `REVOKE`.

### Veja Também

- mysql_set_charset() - Define o conjunto de caracteres do cliente
- mysql_client_encoding() - Retorna o nome do conjunto de caracteres

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open