<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.pg-query-params" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>pg_query_params</refname>

<refpurpose>

Envoie une commande au serveur et attend le résultat, avec les capacités de

passer des paramètres séparément de la commande texte SQL

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>PgSql\Result</type><type>false</type></type><methodname>pg_query_params</methodname>

<methodparam choice="opt"><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>

<methodparam><type>string</type><parameter>query</parameter></methodparam>

<methodparam><type>array</type><parameter>params</parameter></methodparam>

</methodsynopsis>

<para>

Envoie une commande au serveur et attend le résultat, avec les capacités de

passer des paramètres séparément de la commande texte SQL.

</para>

<para>

<function>pg_query_params</function> est comme <function>pg_query</function>,

mais offre des fonctionnalités additionnelles : les valeurs des paramètres

peuvent être spécifiées séparément de la ligne de commande propre.

</para>

<para>

Si des paramètres sont utilisés, ils sont référés à $1, $2, etc. dans

<parameter>query</parameter>. Le même paramètre peut survenir plus d'une fois

dans la requête <parameter>query</parameter> ; la même valeur sera utilisée

dans ce cas. <parameter>params</parameter> spécifie les

valeurs actuelles des paramètres. Une valeur &null; dans ce tableau

signifie que le paramètre correspondant est SQL &null;.

</para>

<para>

Le principal avantage de <function>pg_query_params</function> sur

<function>pg_query</function> est que les valeurs des paramètres peuvent

être séparées de la requête <parameter>query</parameter>, par conséquent,

on évite les échappements de caractères ennuyeux et source d'erreurs.

Contrairement à <function>pg_query</function>,

<function>pg_query_params</function> permet seulement une seule commande

SQL dans la chaîne donnée. (Il peut y avoir des points-virgules à

l'intérieur mais pas plus d'une seule commande.)

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>connection</parameter></term>

<listitem>

&pgsql.parameter.connection-with-unspecified-default;

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>query</parameter></term>

<listitem>

<para>

La requête SQL avec ses paramètres. Elle doit contenir seulement une seule

requête. Plusieurs requêtes séparées par des points-virgules ne sont

pas autorisées. Si des paramètres sont utilisés, ils sont référés à

$1, $2, etc.

</para>

<para>

Les valeurs fournies par l'utilisateur doivent toujours être

passées comme paramètres, et non interpolées dans la chaîne de

requête, où elles peuvent potentiellement former des

<link linkend="security.database.sql-injection">injections SQL</link>

et introduire des bogues lorsque ces données contiennent des guillemets.

Si pour une raison quelconque il n'est pas possible d'utiliser de paramètres,

il faut s'assurer que les valeurs interpolées sont

<link linkend="function.pg-escape-string">proprement échappées</link>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>params</parameter></term>

<listitem>

<para>

Un tableau de valeurs de paramètres pour substituer les variables $1, $2, etc.

dans la requête préparée originale. Le nombre d'éléments présents dans

le tableau doit concorder avec le nombre de variables à remplacer.

</para>

<para>

Les valeurs attendues pour les champs <literal>bytea</literal> ne sont

pas supportées comme paramètres. Utiliser plutôt la fonction

<function>pg_escape_bytea</function> ou utiliser les fonctions sur les

objets larges.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Une instance <classname>PgSql\Result</classname> en cas de succès, &return.falseforfailure;.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

&pgsql.changelog.return-result-object;

&pgsql.changelog.connection-object;

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Exemple avec <function>pg_query_params</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>pg_query</function></member>

</simplelist>

</para>

</refsect1>

</refentry>