DB_common::getOne()

DB_common::getOne() – Runs a query and returns the first column of the first row

Synopsis

mixed &getOne ( string $query , mixed $params = array() )

Description

Runs the query provided and returns the data from the first column of the first row then frees the result set.

Parameter

string $query

the SQL query or the statement to prepare

mixed $params

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

If supplied, prepare()/ execute() is used.

Return value

mixed - the first column's data, NULL if there is no data, or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
DB_ERROR_INVALID invalid SQL statement for preparing is not valid. See the prepare() documentation, if you want to use a SQL statemt using placeholders.
DB_ERROR_MISMATCH mismatch Quantity of parameters didn't match quantity of placeholders in the prepared statement. Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params.
DB_ERROR_NODBSELECTED no database selected No database was chosen. Check the DSN in connect().
every other error code   Database specific error Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Example

Using getOne()

<?php
// Once you have a valid DB object named $db...
$data =& $db->getOne('SELECT cf FROM foo');

if (
PEAR::isError($data)) {
    die(
$data->getMessage());
}

echo 
"$data\n";
?>

Using getOne() with one placeholder

<?php
// Once you have a valid DB object named $db...
$data =& $db->getOne('SELECT cf FROM foo WHERE nf = ?',
        
5);

if (
PEAR::isError($data)) {
    die(
$data->getMessage());
}

echo 
"$data\n";
?>

Using getOne() with two placeholders

<?php
// Once you have a valid DB object named $db...
$data =& $db->getOne('SELECT cf FROM foo WHERE nf IN (?, ?)',
        array(
510));

if (
PEAR::isError($data)) {
    die(
$data->getMessage());
}

echo 
"$data\n";
?>
Views database system information (Previous) Determines current state of a PEAR DB configuration option (Next)
Last updated: Mon, 28 Jul 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: webmaster@metapundit.net
Be careful using getOne() on columns that may contain null values - you now have no way of knowing whether your query matched any rows or not. Consider the table

users
|id|name|
---+----+
1 | test
2 | NULL
---------
<?php
var_dump
($db->getOne('select name from users where id=1'));
var_dump($db->getOne('select name from users where id=2'));
var_dump($db->getOne('select name from users where foo=1'));
?>


will output "NULL", "NULL", and a db_error object.