API:DBAPI:getRow

From MODx Wiki

API Quick reference
Function name:	getRow
Modx versions:	all
Input parameters:	(resource $ds, string $mode)
Return if successful:	An array of column values.
Return type:	mixed
Return on failure:	MySQL error
Object parents:	DocumentParser->DBAPI

When passed a dataset from a SELECT query, this function will return an array of the current row in the dataset. $ds is a required parameter, and must be a dataset. $mode is optional, and accepts three possible values:

1. assoc - Returns an associative array of the current row in the dataset in the form of Table_Field => Value. This is the default value.
2. num - Returns a numerical array of the current row in the dataset.
3. both - Returns an array consisting of both an associative key and numerical key.

Note: using any other value for $mode will result in a MODx error message.

If the current row in the dataset (or the dataset itself) is empty, this function will return false.

Examples

This example uses getRow to return an associative array of a dataset containing music albums. It selects the id, album name, and artist from an 'albums' table of all albums in the table, sorts it by the artist name, and limits it to 50 results:

function getAlbum() {
	$global $modx;
	$output = '';
	$table = $modx->getFullTableName( 'albums' );
	
	$result = $modx->db->select( 'id, album_name, artist', $table, '', 'artist ASC', '0, 50'
	
	if( $modx->db->getRecordCount( $result ) >= 1 ) {
		$output .= '<ul>';
		while( $row = $modx->db->getRow( $result ) ) {
			$output .= '<li>ID: ' . $row['id'] . ' | Album: ' . $row['album_name'] . ' | Artist: ' . $row['artist'] . '</li>';
		}
		$output .= '</ul>';
	}
	else {
		$output = 'There are no records to show.';
	}
	return $output;
}

This example does the same thing, except it uses a numerical array instead of an associative array:

function getAlbum() {
	$global $modx;
	$output = '';
	$table = $modx->getFullTableName( 'albums' );
	
	$result = $modx->db->select( 'id, album_name, artist', $table, '', 'artist ASC', '0, 50'
	
	if( $modx->db->getRecordCount( $result ) >= 1 ) {
		$output .= '<ul>';
		while( $row = $modx->db->getRow( $result, 'num' ) ) {
			$output .= '<li>ID: ' . $row[0] . ' | Album: ' . $row[1] . ' | Artist: ' . $row[2] . '</li>';
		}
		$output .= '</ul>';
	}
	else {
		$output = 'There are no records to show.';
	}
	return $output;
}

As you can see above, the only difference is that it uses numerical indexes rather than indexes consisting of the column name in the table.

Using 'both' for the array type would be just the same, although you could use either the numerical index or the associative key to output the data.

Related Functions

select, query, makeArray, getValue

Function Source

File:	manager/includes/extenders/dbapi.mysql.class.php
line:	272

function getRow($ds, $mode = 'assoc') {
      if ($ds) {
         if ($mode == 'assoc') {
            return mysql_fetch_assoc($ds);
         }
         elseif ($mode == 'num') {
            return mysql_fetch_row($ds);
         }
         elseif ($mode == 'both') {
            return mysql_fetch_array($ds, MYSQL_BOTH);
         } else {
            global $modx;
            $modx->messageQuit("Unknown get type ($mode) specified for fetchRow - must be empty, 'assoc', 'num' or 'both'.");
         }
      }
   }

Notes