Main Menu
PHP Tools
PHP Help Request
PHP Editors Newsletter
Editor Search
Reviewed PHP Editors
Latest News
Submit News
PHP Tutorials
PHP Book Reviews
Online Book Chapters
PHP Games

Forums
RSS 2.0
PHP Desktop Editors
Other PHP Tools
PHP Contests
PHP Programming Help
Linux Help
Apache Help
MySQL Help
PHP Games
PHP Jobs
PHP Forums Home

Programming Contest
PHP Contests
PHP Contests Archive

Documentation
PHP Manual
PEAR Manual
PHP-GTK Manual
Smarty Manual
PostgreSQL Manual
CSS 2 Reference
Redhat Linux 9
HTML 4.01
Apache 2 Manual

Partner Sites
Ajax Tutorials
Webmaster Resources
Web Templates
PHP Scripts
PHP Code Examples
Learn PHP playing Trivia
PHP & MySQL Forums
Web Development Index
web site templates

Sponsors

NuSphere

DB_common::getAssoc()
PEAR Manual
PrevNext

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

Table 33-1. Possible PEAR_Error values

Error codeError messageReasonSolution
DB_ERROR_INVALID invalid SQL statment 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 statment. 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 choosen. 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 statment. Ie. using LIMIT in a SQL-Statment 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.

Example 33-1. 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);
?>

Output: 

Array
(
    [Juan] => 1991-01-11 21:31:41
    [Kyu] => 1993-03-13 23:33:43
)

Example 33-2. 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);
?>

Output: 

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

Example 33-3. 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);
?>

Output: 

Array
(
    [Juan] => Array
        (
            [0] => 1991-01-11 21:31:41
        )
    [Kyu] => Array
        (
            [0] => 1993-03-13 23:33:43
        )
)

Example 33-4. 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);
?>

Output: 

Array
(
    [Juan] => Array
        (
            [df] => 1991-01-11 21:31:41
        )
    [Kyu] => Array
        (
            [df] => 1993-03-13 23:33:43
        )
)

Example 33-5. 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);
?>

Output: 

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

Example 33-6. 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);
?>

Output: 

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

Example 33-7. 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);
?>

Output: 

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

Example 33-8. 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);
?>

Output: 

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

Example 33-9. 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);
?>

Output: 

Array
(
    [Juan] => Array
        (
            [0] => 5
            [1] => 1991-01-11 21:31:41
        )
    [Kyu] => Array
        (
            [0] => 15
            [1] => 1993-03-13 23:33:43
        )
)

Example 33-10. 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);
?>

Output: 

Array
(
    [Juan] => Array
        (
            [nf] => 5
            [df] => 1991-01-11 21:31:41
        )
    [Kyu] => Array
        (
            [nf] => 15
            [df] => 1993-03-13 23:33:43
        )
)

Example 33-11. 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);
?>

Output: 

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

Example 33-12. 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);
?>

Output: 

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

Example 33-13. 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);
?>

Output: 

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

Example 33-14. 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);
?>

Output: 

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

Example 33-15. 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());
}
?>

Example 33-16. 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());
}
?>

See

setFetchMode(), getOne(), getRow(), getCol(), getAll(), query(), "Intro - Prepare & Execute"

PrevHomeNext
DB_common::getAll()UpDB_common::getCol()
© Copyright 2003-2023 www.php-editors.com. The ultimate PHP Editor and PHP IDE site.