Solar_Sql_Adapter::query()
Prev Solar_Sql_Adapter Next

Solar_Sql_Adapter::query()

public PDOStatement Solar_Sql_Adapter::query ( string $stmt , array $data = array () )

Prepares and executes an SQL statement, optionally binding values to named parameters in the statement.

Parameters

  • (string) $stmt: The text of the SQL statement, optionally with named placeholders.

  • (array) $data: An associative array of data to bind to the named placeholders.

Returns

  • (PDOStatement)

Description

Prepares and executes an SQL statement, optionally binding values to named parameters in the statement.

This is the most-direct way to interact with the database; you pass an SQL statement to the method, then the adapter uses » PDO to execute the statement and return a result.

<?php
$sql = Solar::factory('Solar_Sql');

// $result is a PDOStatement
$result = $sql->query('SELECT * FROM table');

To help prevent SQL injection attacks, you should always quote the values used in a direct query. Use quote(), quoteInto(), or quoteMulti() to accomplish this. Even easier, use the automated value binding provided by the query() method:

<?php
// BAD AND SCARY:
$result = $sql->query('SELECT * FROM table WHERE foo = $bar');

// Much much better:
$result = $sql->query(
    'SELECT * FROM table WHERE foo = :bar',
    array('bar' => $bar)
);

Note that adapters provide convenience methods to automatically quote values on common operations:

Additionally, the Solar_Sql_Select class is dedicated to safely creating portable SELECT statements, so you may wish to use that instead of writing literal SELECTs.

Automated Binding of Values in PHP 5.2.1 and Later

With PDO in PHP 5.2.1 and later, we can no longer just throw an array of data at the statement for binding. We now need to bind values specifically to their respective placeholders.

In addition, we can't bind one value to multiple identical named placeholders; we need to bind that same value multiple times. So if :foo is used three times, PDO uses :foo the first time, :foo2 the second time, and :foo3 the third time.

This query() method examins the statement for all :name placeholders and attempts to bind data from the $data array. The regular-expression it uses is a little braindead; it cannot tell if the :name placeholder is literal text or really a place holder.

As such, you should either use the $data array for named-placeholder value binding at query() time, or bind-as-you-go when building the statement, not both. If you do, you are on your own to make sure that nothing looking like a :name placeholder exists in the literal text.

Question-mark placeholders are not supported for automatic value binding at query() time.

Prev Up Next
Solar_Sql_Adapter::nextSequence() Home Solar_Sql_Adapter::quote()

Local