Flourish PHP Unframework

fUnbufferedResult

The fUnbufferedResult class is an iterable result object that is returned when an SQL query is executed. It contains similar information to fResult, however some features are missing due to the nature of the results not being buffered. The quality of being unbuffered causes this object to use less memory than an fResult object.

Creation

The fUnbufferedResult class can be created by executing the methods fDatabase::unbufferedQuery() or fDatabase::unbufferedTranslatedQuery().

// Creation of fUnbufferedResult from a normal query
$result = $db->unbufferedQuery("SELECT * FROM users");

// Creation of an fUnbufferedResult object from a translated query
$result2 = $db->unbufferedTranslatedQuery("SELECT * FROM users LIMIT 5");

Row Format

By default when retrieving rows from an unbuffered result object, they are returned as associative arrays. In the case of Oracle databases, where columns are case-insensitive, the array keys are lowercase.

It is possible to retrieve stdClass objects back for each row instead of associative arrays. This is done by calling the method asObjects(). The method returns the fUnbufferedResult object, allowing for method chaining:

// Set the result to return objects
$res = $db->unbufferedQuery("SELECT * FROM users")->asObjects();

If you are looking for objects with more functionality, please see fActiveRecord.

Unescaping Data

While it is certainly possible to manually unescape data from a result set, one row and column at a time, unescaping the whole result is often much easier. The method unescape() accepts an associative array of the column name as the key and the data type as the value. This method should be called before any rows are fetched.

$result = $db->unbufferedQuery("SELECT * FROM users");
$result->unescape(array(
    'first_name'       => 'string',
    'last_name'        => 'string',
    'is_authenticated' => 'boolean',
    'last_login'       => 'timestamp'
));

foreach ($result as $row) {
    // $row now contains the data in native PHP data types
}

Iteration

The fUnbufferedResult class implements the Iterator interface, which means that you can use the foreach construct to loop through all resulting rows. Below is an example of iterating over a result:

$result = $db->unbufferedQuery("SELECT * FROM users");

foreach ($result as $row) {
    echo $row['name'] . '<br />';
}

If the result did not return any rows, the foreach construct will not be looped at all and the execution of the code will continue. If you wish to execute different code if no rows are returned, see the next section about exceptions.

If you wish to to manual iteration you can use the fetchRow() and valid() methods as shown below:

// Iteration using valid() and fetchRow()
while ($result->valid()) {
    $row = $result->fetchRow();
}

Exceptions

As mentioned in the last section, if you iterate through the result and no rows are returned, nothing will happen. If you do need to execute different code when no rows are returned, you will want to call the tossIfNoRows() to cause an fNoRowsException to be thrown:

try {
    $result = $db->unbufferedQuery("SELECT * FROM users");
    $result->tossIfNoRows();
    ?>
    <h1>Users</h1>
    <?
    foreach ($result as $row) {
        echo $row['name'] . '<br />';
    }
} catch (fNoRowsException $e) {
    ?>
    <p>No users were found</p>
    <?php
}

In addition to calling tossIfNoRows(), an fNoRowsException will be thrown if any Iterator interface methods (such as current(), next(), etc) or fetchRow() is called on a result object which returned no rows.

Query Info

Since fUnbufferedResult does not use buffering, only a fraction of the information about a query is available compared to the fResult class.

Method Description
getSQL() Returns the SQL statement executed for this result
getUntranslatedSQL() Returns the SQL from before translation happened - only applicable for results from unbufferedTranslatedQuery()