# pg_prepare

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

pg_prepare — Envoie une requête au serveur pour créer une instruction préparée avec les paramètres donnés et attend l'exécution

### Description

pg_prepare(PgSql\Connection `$connection` = ?, string `$stmtname`, string `$query`): PgSql\Result|false

pg_prepare() crée une requête préparée pour une exécution ultérieure avec pg_execute() ou pg_send_execute(). Cette caractéristique permet aux commandes qui seront utilisées à plusieurs reprises d'être analysées et planifiées qu'une seule fois, plutôt que d'être exécutées chaque fois. pg_prepare() est supportée seulement avec les versions PostgreSQL 7.4 ou plus récentes; la commande échouera si vous l'utilisez avec des versions antérieures.

La fonction crée une requête préparée nommée `stmtname` à partir de la chaîne `query`, celle-ci doit contenir qu'une seule commande SQL. `stmtname` peut être `""` pour créer une requête qui n'est pas nommée. Dans ce cas, les requêtes qui existaient et qui se trouvaient sans noms sont automatiquement remplacées; autrement, il y aura une erreur si le nom de la requête est déjà défini dans la session courante. Si des paramètres sont utilisés, ils sont référés à `$1`, `$2`, etc. dans `query`.

Des requêtes préparées à utiliser avec pg_prepare() peuvent être aussi créées en exécutant la requête SQL `PREPARE`. (Par contre, pg_prepare() est plus flexible puisqu'elle ne nécessite pas que les types des paramètres soit préspécifiés.) De plus, bien qu'il n'y a pas de fonction PHP pour supprimer une requête préparée, la requête SQL `DEALLOCATE` peut être utilisé pour ce motif.

### Liste de paramètres

`connection`

  Une instance PgSql\Connection. Quand `connection` est pas spécifié, la connexion par défaut est utilisé. La connexion par défaut est la dernière connexion faite par pg_connect() ou pg_pconnect()

  Avertissement

  À partir de PHP 8.1.0, utiliser la connexion par défaut est obsolète.

`stmtname`

  Le nom à donner à la requête préparée. Il doit être unique à chaque session. Si une chaîne vide est spécifiée `""` alors une requête sans nom est créée, écrasant les requêtes sans noms précédemment définies.

`query`

  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.

### Valeurs de retour

Une instance PgSql\Result en cas de succès, ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.1.0 | Retourne désormais une instance de PgSql\Result instance ; auparavant, une resource était retourné.
8.1.0 | Le paramètre `connection` attend désormais une instance de PgSql\Connection ; auparavant, une resource était attendu.

### Exemples

Exemple #1 Exemple avec pg_prepare()

`<?php
// Connexion à une base de données nommée "marie"
$dbconn = pg_connect("dbname=marie");
// Prépare une requête pour l'exécution
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');
// Exécute la requête préparée. Notez qu'il n'est pas nécessaire d'échapper
// la chaîne "Joe's Widgets"
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));
// Exécute la même requête préparée, cette fois avec un paramètre différent
$result = pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));
?>`

### Voir aussi

- pg_execute() - Exécute une requête préparée PostGreSQL
- pg_send_execute() - Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)