DataSet

The DataSet class represents a collection of data results from a query. It provides methods to navigate and manipulate the result set.

Methods

addDataPair($key, $value)

Adds a single column-value pair to the dataset. If the key already exists, its value is overwritten.

Example:

use Staple\Query\DataSet;

$ds = new DataSet();
$ds->addDataPair('username', 'jdoe');

addData(array $data)

Appends multiple column-value pairs from an associative array to the dataset. Existing string keys are overwritten.

Example:

use Staple\Query\DataSet;

$ds = new DataSet();
$ds->addData(['first_name' => 'John', 'last_name' => 'Doe']);

setData(array $data)

Clears any current data in the dataset and replaces it with the provided associative array.

Example:

use Staple\Query\DataSet;

$ds = new DataSet(['email' => 'john@example.com']);
$ds->setData(['email' => 'jane@example.com']); // email is now jane@example.com

addLiteralColumn($column, $data)

Adds a column where the value is treated as literal SQL and will not be escaped or parameterized.

Example:

use Staple\Query\DataSet;

$ds = new DataSet();
$ds->addLiteralColumn('created_at', 'NOW()');
// Result in SQL: created_at = NOW()

addLiteralData(array $data)

Adds multiple literal SQL columns from an associative array.

Example:

use Staple\Query\DataSet;

$ds = new DataSet();
$ds->addLiteralData([
    'updated_at' => 'CURRENT_TIMESTAMP',
    'version' => 'version + 1'
]);

getColumns()

Returns an array of all column names currently in the dataset.

Example:

$ds = new DataSet(['a' => 1, 'b' => 2]);
$columns = $ds->getColumns(); // ['a', 'b']

count()

Returns the number of elements in the dataset.

current()

Returns the current element during iteration.

next()

Moves the internal pointer to the next element.

key()

Returns the key of the current element.

valid()

Checks if the current position is valid.

rewind()

Rewinds the internal pointer to the first element.

getInsertString()

Generates the SQL string fragment for an INSERT statement (e.g., (col1, col2) VALUES (:col1, :col2)).

getUpdateString()

Generates the SQL string fragment for an UPDATE statement (e.g., col1=:col1, col2=:col2).