pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Envia um comando ao servidor e aguarda o resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL

Descrição

pg_query_params(PgSql\Connection $connection = ?, string $query, array $params): PgSql\Result|false

Envia um comando ao servidor e aguarda o resultado, podendo passar parâmetros separadamente do texto do comando SQL.

pg_query_params() é como pg_query(), mas oferece funcionalidade adicional: os valores dos parâmetros podem ser especificados separadamente da string de comando propriamente dita.

Se parâmetros forem usados, eles serão referidos na string query como $1, $2, etc. O mesmo parâmetro pode aparecer mais de uma vez na query; o mesmo valor será usado nesse caso. params especifica os valores reais dos parâmetros. Um valor null neste array significa que o parâmetro correspondente é SQL NULL.

A principal vantagem de pg_query_params() sobre pg_query() é que os valores dos parâmetros podem ser separados da string query, evitando assim a necessidade de tarefas tediosas e propensas a erros de escape. Ao contrário de pg_query(), pg_query_params() permite no máximo um comando SQL na string fornecida. (Pode haver ponto-e-vírgula, mas não mais do que um comando não vazio.)

Parâmetros

connection

Uma instância de PgSql\Connection. Quando o parâmetro connection não for especificado, a conexão padrão será usada. A conexão padrão é a última conexão feita por pg_connect() ou pg_pconnect().

Aviso

A partir do PHP 8.1.0, usar a conexão padrão foi descontinuado.

query

A instrução SQL parametrizada. Deve conter apenas uma única instrução. (múltiplas instruções separadas por ponto e vírgula não são permitidas.) Se algum parâmetro for usado, ele será chamado de $1, $2, etc.

Os valores fornecidos pelo usuário devem sempre ser passados como parâmetros, não interpolados na string de consulta, onde formam possíveis vetores de ataque de injeção de SQL e introduzem bugs ao manipular dados contendo aspas. Se por algum motivo você não puder usar um parâmetro, certifique-se de que os valores interpolados foram escapados corretamente.

params

Um array de valores de parâmetros para substituir os espaços reservados $1, $2, etc. na string de consult original preparada. O número de elementos no array deve corresponder ao número de espaços reservados.

Valores destinados a campos bytea não são suportados como parâmetros. Use pg_escape_bytea() ou use as funções de objetos grandes.

Valor Retornado

Uma instância PgSql\Result em caso de sucesso, ou false em caso de falha.

Registro de Alterações

Versão	Descrição
8.1.0	Agora retorna uma instância de PgSql\Result; anteriormente, um resource era retornado.
8.1.0	O parâmetro `connection` agora espera uma instância de PgSql\Connection; anteriormente, um resource era esperado.

Exemplos

Exemplo #1 Usando pg_query_params()

<?php
// Conecta a um banco de dados chamado "mary"
$dbconn = pg_connect("dbname=mary");

// Encontre todas as lojas chamadas Joe's Widgets. Observe que não é necessário
// escapar "Joe's Widgets"
$result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

// Compara com apenas o uso de pg_query
$str = pg_escape_string("Joe's Widgets");
$result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

?>

Veja Também

pg_query() - Executa uma consulta