<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Executes a prepared statement</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="pdostatement.errorinfo.html">PDOStatement::errorInfo</a></div>
<div class="next" style="text-align: right; float: right;"><a href="pdostatement.fetch.html">PDOStatement::fetch</a></div>
<div class="up"><a href="class.pdostatement.html">PDOStatement</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="pdostatement.execute" class="refentry">
<div class="refnamediv">
<h1 class="refname">PDOStatement::execute</h1>
<p class="verinfo">(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)</p><p class="refpurpose"><span class="refname">PDOStatement::execute</span> — <span class="dc-title">
Executes a prepared statement
</span></p>
</div>
<div class="refsect1 description" id="refsect1-pdostatement.execute-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>PDOStatement::execute</strong></span>
([ <span class="methodparam"><span class="type">array</span> <code class="parameter">$input_parameters</code></span>
] )</div>
<p class="para rdfs-comment">
Execute the prepared statement. If the prepared statement included
parameter markers, you must either:
<ul class="itemizedlist">
<li class="listitem"><p class="para">call <span class="function"><a href="pdostatement.bindparam.html" class="function">PDOStatement::bindParam()</a></span> to bind PHP variables
to the parameter markers: bound variables pass their value as input and receive the
output value, if any, of their associated parameter markers</p></li>
<li class="listitem"><p class="para">or pass an array of input-only parameter values</p></li>
</ul>
</p>
</div>
<div class="refsect1 parameters" id="refsect1-pdostatement.execute-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">input_parameters</code></em></span>
<dd>
<p class="para">
An array of values with as many elements as there are bound
parameters in the SQL statement being executed.
All values are treated as <strong><code>PDO::PARAM_STR</code></strong>.
</p>
<p class="para">
You cannot bind multiple values to a single parameter; for example,
you cannot bind two values to a single named parameter in an IN()
clause.
</p>
<p class="para">
You cannot bind more values than specified; if more keys exist in
<em><code class="parameter">input_parameters</code></em> than in the SQL specified
in the <span class="methodname"><a href="pdo.prepare.html" class="methodname">PDO::prepare()</a></span>, then the statement will
fail and an error is emitted.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-pdostatement.execute-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-pdostatement.execute-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.2.0</td>
<td>
The keys from <em><code class="parameter">input_parameters</code></em> must match the ones
declared in the SQL. Before PHP 5.2.0 this was silently ignored.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-pdostatement.execute-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-945"><p><strong>Example #1 Execute a prepared statement with bound variables</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Execute a prepared statement by binding PHP variables */<br /></span><span style="color: #0000BB">$calories </span><span style="color: #007700">= </span><span style="color: #0000BB">150</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$colour </span><span style="color: #007700">= </span><span style="color: #DD0000">'red'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$sth </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT name, colour, calories<br /> FROM fruit<br /> WHERE calories < :calories AND colour = :colour'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">bindParam</span><span style="color: #007700">(</span><span style="color: #DD0000">':calories'</span><span style="color: #007700">, </span><span style="color: #0000BB">$calories</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">PARAM_INT</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">bindParam</span><span style="color: #007700">(</span><span style="color: #DD0000">':colour'</span><span style="color: #007700">, </span><span style="color: #0000BB">$colour</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">PARAM_STR</span><span style="color: #007700">, </span><span style="color: #0000BB">12</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-946"><p><strong>Example #2 Execute a prepared statement with an array of insert values (named parameters)</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Execute a prepared statement by passing an array of insert values */<br /></span><span style="color: #0000BB">$calories </span><span style="color: #007700">= </span><span style="color: #0000BB">150</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$colour </span><span style="color: #007700">= </span><span style="color: #DD0000">'red'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$sth </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT name, colour, calories<br /> FROM fruit<br /> WHERE calories < :calories AND colour = :colour'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">(array(</span><span style="color: #DD0000">':calories' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$calories</span><span style="color: #007700">, </span><span style="color: #DD0000">':colour' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$colour</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-947"><p><strong>Example #3 Execute a prepared statement with an array of insert values (placeholders)</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Execute a prepared statement by passing an array of insert values */<br /></span><span style="color: #0000BB">$calories </span><span style="color: #007700">= </span><span style="color: #0000BB">150</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$colour </span><span style="color: #007700">= </span><span style="color: #DD0000">'red'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$sth </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT name, colour, calories<br /> FROM fruit<br /> WHERE calories < ? AND colour = ?'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">(array(</span><span style="color: #0000BB">$calories</span><span style="color: #007700">, </span><span style="color: #0000BB">$colour</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-948"><p><strong>Example #4 Execute a prepared statement with question mark placeholders</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Execute a prepared statement by binding PHP variables */<br /></span><span style="color: #0000BB">$calories </span><span style="color: #007700">= </span><span style="color: #0000BB">150</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$colour </span><span style="color: #007700">= </span><span style="color: #DD0000">'red'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$sth </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT name, colour, calories<br /> FROM fruit<br /> WHERE calories < ? AND colour = ?'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">bindParam</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">$calories</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">PARAM_INT</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">bindParam</span><span style="color: #007700">(</span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">$colour</span><span style="color: #007700">, </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">PARAM_STR</span><span style="color: #007700">, </span><span style="color: #0000BB">12</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-949"><p><strong>Example #5 Execute a prepared statement using array for IN clause</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Execute a prepared statement using an array of values for an IN clause */<br /></span><span style="color: #0000BB">$params </span><span style="color: #007700">= array(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">21</span><span style="color: #007700">, </span><span style="color: #0000BB">63</span><span style="color: #007700">, </span><span style="color: #0000BB">171</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">/* Create a string for the parameter placeholders filled to the number of params */<br /></span><span style="color: #0000BB">$place_holders </span><span style="color: #007700">= </span><span style="color: #0000BB">implode</span><span style="color: #007700">(</span><span style="color: #DD0000">','</span><span style="color: #007700">, </span><span style="color: #0000BB">array_fill</span><span style="color: #007700">(</span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #0000BB">count</span><span style="color: #007700">(</span><span style="color: #0000BB">$params</span><span style="color: #007700">), </span><span style="color: #DD0000">'?'</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*<br /> This prepares the statement with enough unnamed placeholders for every value<br /> in our $params array. The values of the $params array are then bound to the<br /> placeholders in the prepared statement when the statement is executed.<br /> This is not the same thing as using PDOStatement::bindParam() since this<br /> requires a reference to the variable. PDOStatement::execute() only binds<br /> by value instead.<br />*/<br /></span><span style="color: #0000BB">$sth </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT id, name FROM contacts WHERE id IN (</span><span style="color: #0000BB">$place_holders</span><span style="color: #DD0000">)"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$sth</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">(</span><span style="color: #0000BB">$params</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 notes" id="refsect1-pdostatement.execute-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Some drivers require to <a href="pdostatement.closecursor.html" class="link">close
cursor</a> before executing next statement.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-pdostatement.execute-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="pdo.prepare.html" class="function" rel="rdfs-seeAlso">PDO::prepare()</a> - Prepares a statement for execution and returns a statement object</span></li>
<li class="member"> <span class="function"><a href="pdostatement.bindparam.html" class="function" rel="rdfs-seeAlso">PDOStatement::bindParam()</a> - Binds a parameter to the specified variable name</span></li>
<li class="member"> <span class="function"><a href="pdostatement.fetch.html" class="function" rel="rdfs-seeAlso">PDOStatement::fetch()</a> - Fetches the next row from a result set</span></li>
<li class="member"> <span class="function"><a href="pdostatement.fetchall.html" class="function" rel="rdfs-seeAlso">PDOStatement::fetchAll()</a> - Returns an array containing all of the result set rows</span></li>
<li class="member"> <span class="function"><a href="pdostatement.fetchcolumn.html" class="function" rel="rdfs-seeAlso">PDOStatement::fetchColumn()</a> - Returns a single column from the next row of a result set</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="pdostatement.errorinfo.html">PDOStatement::errorInfo</a></div>
<div class="next" style="text-align: right; float: right;"><a href="pdostatement.fetch.html">PDOStatement::fetch</a></div>
<div class="up"><a href="class.pdostatement.html">PDOStatement</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
