DB_common::getAssoc()
DB_common::getAssoc() -- Runs a query and returns the data as an array
Synopsis
array &getAssoc (
string $query
,
boolean $force_array = FALSE
,
mixed $params = array()
,
integer $fetchmode =
DB_FETCHMODE_DEFAULT
,
boolean $group = FALSE
)
Description
Runs the query provided and puts the
entire result set into an associative array
then frees the result set.
If the result set contains more than two columns, the value
will be an array of the values from column 2 to n. If the result
set contains only two columns, the returned value will be a
scalar with the value of the second column (unless forced to an
array with the $force_array
parameter).
Parameter
-
string
$query
-
the SQL query or the statement to prepare
-
boolean
$force_array
-
used only if the query returns
exactly two columns.
If TRUE, the values of the returned array
will be one-element arrays instead of scalars.
-
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.
-
integer
$fetchmode
-
the fetch mode to use.
The default is DB_FETCHMODE_DEFAULT,
which tells this method to use DB's current fetch mode.
DB's current default fetch mode can be changed using
setFetchMode().
Potential values include:
-
DB_FETCHMODE_ORDERED
-
DB_FETCHMODE_ASSOC
-
DB_FETCHMODE_OBJECT
-
boolean
$group
-
if TRUE, the values of
the returned array is wrapped in another array.
If the same key value (in the first column)
repeats itself, the values
will be appended to this array instead
of overwriting the
existing values.
Return value
array - associative array with the query results
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().
|
| DB_ERROR_TRUNCATED |
truncated
|
The result set contains fewer then two columns
|
Check the SQL query or choose another
get*() function
|
| 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
All of the examples use the following data set:
INSERT INTO foo VALUES ('Juan', 5, '1991-01-11 21:31:41');
INSERT INTO foo VALUES ('Kyu', 10, '1992-02-12 22:32:42');
INSERT INTO foo VALUES ('Kyu', 15, '1993-03-13 23:33:43');
|
Result sets having two columns
When using getAssoc() for results
which have two columns and
$force_array
= FALSE (the default)
changing $fetchmode
has no
impact on the format of the resulting array.
Using getAssoc() in default mode
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo');
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => 1991-01-11 21:31:41
[Kyu] => 1993-03-13 23:33:43
)
|
Using getAssoc() with
$group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
false, array(), DB_FETCHMODE_ORDERED, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => 1991-01-11 21:31:41
)
[Kyu] => Array
(
[0] => 1992-02-12 22:32:42
[1] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$force_array
= TRUE
and $fetchmode
=
DB_FETCHMODE_ORDERED
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
true, array(), DB_FETCHMODE_ORDERED);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => 1991-01-11 21:31:41
)
[Kyu] => Array
(
[0] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$force_array
= TRUE
and $fetchmode
=
DB_FETCHMODE_ASSOC
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
true, array(), DB_FETCHMODE_ASSOC);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[df] => 1991-01-11 21:31:41
)
[Kyu] => Array
(
[df] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$force_array
= TRUE
and $fetchmode
=
DB_FETCHMODE_OBJECT
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
true, array(), DB_FETCHMODE_OBJECT);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => stdClass Object
(
[cf] => Juan
[df] => 1991-01-11 21:31:41
)
[Kyu] => stdClass Object
(
[cf] => Kyu
[df] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$force_array
= TRUE,
$fetchmode
=
DB_FETCHMODE_ORDERED
and $group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
true, array(), DB_FETCHMODE_ORDERED, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => Array
(
[0] => 1991-01-11 21:31:41
)
)
[Kyu] => Array
(
[0] => Array
(
[0] => 1992-02-12 22:32:42
)
[1] => Array
(
[0] => 1993-03-13 23:33:43
)
)
)
|
Using getAssoc() with
$force_array
= TRUE,
$fetchmode
=
DB_FETCHMODE_ASSOC
and $group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
true, array(), DB_FETCHMODE_ASSOC, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => Array
(
[df] => 1991-01-11 21:31:41
)
)
[Kyu] => Array
(
[0] => Array
(
[df] => 1992-02-12 22:32:42
)
[1] => Array
(
[df] => 1993-03-13 23:33:43
)
)
)
|
Using getAssoc() with
$force_array
= TRUE,
$fetchmode
=
DB_FETCHMODE_OBJECT
and $group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo',
true, array(), DB_FETCHMODE_OBJECT, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => stdClass Object
(
[cf] => Juan
[df] => 1991-01-11 21:31:41
)
)
[Kyu] => Array
(
[0] => stdClass Object
(
[cf] => Kyu
[df] => 1992-02-12 22:32:42
)
[1] => stdClass Object
(
[cf] => Kyu
[df] => 1993-03-13 23:33:43
)
)
)
|
Result sets having more than two columns
Using getAssoc() with
$fetchmode
=
DB_FETCHMODE_ORDERED
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',
false, array(), DB_FETCHMODE_ORDERED);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => 5
[1] => 1991-01-11 21:31:41
)
[Kyu] => Array
(
[0] => 15
[1] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$fetchmode
=
DB_FETCHMODE_ASSOC
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',
false, array(), DB_FETCHMODE_ASSOC);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[nf] => 5
[df] => 1991-01-11 21:31:41
)
[Kyu] => Array
(
[nf] => 15
[df] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$fetchmode
=
DB_FETCHMODE_OBJECT
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',
false, array(), DB_FETCHMODE_OBJECT);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => stdClass Object
(
[cf] => Juan
[nf] => 5
[df] => 1991-01-11 21:31:41
)
[Kyu] => stdClass Object
(
[cf] => Kyu
[nf] => 15
[df] => 1993-03-13 23:33:43
)
)
|
Using getAssoc() with
$fetchmode
=
DB_FETCHMODE_ORDERED
and $group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',
false, array(), DB_FETCHMODE_ORDERED, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => Array
(
[0] => 5
[1] => 1991-01-11 21:31:41
)
)
[Kyu] => Array
(
[0] => Array
(
[0] => 10
[1] => 1992-02-12 22:32:42
)
[1] => Array
(
[0] => 15
[1] => 1993-03-13 23:33:43
)
)
)
|
Using getAssoc() with
$fetchmode
=
DB_FETCHMODE_ASSOC
and $group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',
false, array(), DB_FETCHMODE_ASSOC, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => Array
(
[nf] => 5
[df] => 1991-01-11 21:31:41
)
)
[Kyu] => Array
(
[0] => Array
(
[nf] => 10
[df] => 1992-02-12 22:32:42
)
[1] => Array
(
[nf] => 15
[df] => 1993-03-13 23:33:43
)
)
)
|
Using getAssoc() with
$fetchmode
=
DB_FETCHMODE_OBJECT
and $group
= TRUE
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',
false, array(), DB_FETCHMODE_OBJECT, true);
if (PEAR::isError($data)) {
die($data->getMessage());
}
print_r($data);
?>
|
Array
(
[Juan] => Array
(
[0] => stdClass Object
(
[cf] => Juan
[nf] => 5
[df] => 1991-01-11 21:31:41
)
)
[Kyu] => Array
(
[0] => stdClass Object
(
[cf] => Kyu
[nf] => 10
[df] => 1992-02-12 22:32:42
)
[1] => stdClass Object
(
[cf] => Kyu
[nf] => 15
[df] => 1993-03-13 23:33:43
)
)
)
|
Prepare / Execute Mode
Using getAssoc()
with one placeholder
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo WHERE nf = ?',
false, 5);
if (PEAR::isError($data)) {
die($data->getMessage());
}
?>
|
Using getAssoc()
with two placeholders
<?php
// Once you have a valid DB object named $db...
$data =& $db->getAssoc('SELECT cf, df FROM foo WHERE nf IN (?, ?)',
false, array(5, 10));
if (PEAR::isError($data)) {
die($data->getMessage());
}
?>
|