====== param ======
~~NOTOC~~
<WRAP right box>
==See Also==
[[v5:reference:connection:addq|addQ()]]\\
== Syntax ==
  string param(
         string $name
         )
</WRAP>
===== Description =====
The function param returns a database-specific placeholder for a prepared query statement. 

This method is used with [[v5:userguide:learn_bind:bind_vars|bind variable SQL statement execution]], to produce injection resistant code.

On RDBMS with positional (numbered) query parameters such as PostgreSQL, calling ''param()'' with a "falsy" value((equivalent to ''false''; read the //Converting to boolean// section in the [[https://www.php.net/manual/en/language.types.boolean.php|PHP manual]])) will reset the parameter counter, allowing to start building a new query without first executing the previous one.

<WRAP tip>
Note that calling ''param(false)'' **only** resets the counter, //without returning a placeholder//. This allows forcing a reset operation independently from building a query; the next invocation will return the first placeholder.

Compare that with ''param(0)'' or ''param(%%''%%)'', which both resets **and** returns the first placeholder.

This is illustrated in the examples below.
</WRAP>



------------------------------
===== Usage =====

This is an example of how to use param() to build SQL queries:

<code php>
$sql1 = 'SELECT * FROM accounts WHERE ' 
    . 'name = '  . $db->param('account') . ' AND '
    . 'total = ' . $db->param('amount');

// Reset param count as a standalone operation then build the query
$db->param(false);
$sql2 = 'SELECT * FROM accounts WHERE id = ' . $db->param('id');

// Reset param count with a "falsy" value while building the query
$sql3 = 'SELECT * FROM accounts WHERE '
    . 'name = ' . $db->param(0) . ' AND '
    . 'status = ' . $db->param(1);
</code>



See below for the code's output with various database drivers.

==== MySQL, IBM DB2 ====
<code>
$sql1: SELECT * FROM accounts WHERE name = ? AND total = ?
$sql2: SELECT * FROM accounts WHERE id = ?
$sql3: SELECT * FROM accounts WHERE name = ? AND status = ?
</code>

==== Oracle (oci8) ====
<code>
$sql1: SELECT * FROM accounts WHERE name = :account AND total = :amount
$sql2: SELECT * FROM accounts WHERE id = :id
$sql3: SELECT * FROM accounts WHERE name = :0 AND status = :1
</code>

==== PostgreSQL ====
<code>
$sql1: SELECT * FROM accounts WHERE name = $1 AND total = $2
$sql2: SELECT * FROM accounts WHERE id = $1
$sql3: SELECT * FROM accounts WHERE name = $1 AND status = $2
</code>

Without the parameter reset, //$sql2// would be ''... id = $3'' and //$sql3// ''... name = $4 AND status = $5'', which would result in errors when calling [[v5:reference:connection:execute|]].