param

Syntax

string param(
       string $name
       )

Description

The function param returns a database-specific placeholder for a prepared query statement.

This method is used with 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¹⁾ will reset the parameter counter, allowing to start building a new query without first executing the previous one.

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.

Usage

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

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

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

MySQL, IBM DB2

$sql1: SELECT * FROM accounts WHERE name = ? AND total = ?
$sql2: SELECT * FROM accounts WHERE id = ?
$sql3: SELECT * FROM accounts WHERE name = ? AND status = ?

Oracle (oci8)

$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

PostgreSQL

$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

Without the parameter reset, $sql2 would be … id = $3 and $sql3 … name = $4 AND status = $5, which would result in errors when calling execute.

¹⁾

equivalent to false; read the Converting to boolean section in the PHP manual