Docs For Class atkStatement

Home

Documentation home

Atk index

Docs For Class atkStatement [ package: atk ]

Class: atkStatement

Source Location: /db/statement/class.atkstatement.inc

Class atkStatement

Class Overview

Implements interfaces:

IteratorAggregate (internal interface)

A statement can be used to execute a query.

The query can be re-used, e.g. executed multiple times, and may contain bind parameters. Both named and anonymous bind parameters are supported, but can't be mixed together. Named bind parameters are in the form of ":name", anonymous bind parameters are simply represented by a "?".

When fetching rows for a given query you can either use an iterator (efficient one-by-one retrieval of rows) or one of the convenience methods (e.g. getFirstRow, getAllRows, ...).

To create an instance please use the atkDb::prepare($query) method.

Example: $stmt = atkGetDb()->prepare("SELECT COUNT(*) FROM people WHERE birthday > :birthday"); $stmt->execute(array('birthday' => '1985-09-20')); foreach ($stmt as $person) { echo "{$person['firstname']} {$person['lastname'}\n"; } $stmt->close();

Located in /db/statement/class.atkstatement.inc [line 48]

Wiki documentation

Author(s):

Peter C. Verhage <peter@achievo.org>

API Tags:

Abstract:

Information Tags:

Properties

Methods

[ Top ]

Descendants

Child Class	Description
atkCompatStatement	Base statement class used for database drivers which don't have their own implementation.
atkMySQLiStatement	MySQLi statement implementation.

[ Top ]

Property Summary

array	$m_bindPositions	Positions of bind parameters.
array	$m_latestParams	Latest parameters supplied to the execute() method.
string	$m_parsedQuery	Parsed SQL query.
int	$m_position	Current row offset position.
string	$m_query	(Original) SQL query.

[ Top ]

Method Summary

atkStatement	__construct()	Constructs a new statement for the given query.
void	__destruct()	Destructor.
void	close()	Close this statement.
void	execute()	Executes the statement.
mixed	fetch()	Fetches the next row from the result set.
void	getAffectedRowCount()	Returns the number of affected rows in case of an INSERT, UPDATE or DELETE query.
array	getAllRows()	Get all rows for the given query.
array	getAllRowsAssoc()	Get rows in an associative array with the given column used as key for the rows.
array	getAllValues()	Get an array with all the values in the specified column.
array	getAllValuesAssoc()	Get rows in an associative array with the given key column used as key and the given value column used as value.
atkDb	getDb()	Returns the database instance.
array	getFirstRow()	Returns the first row.
mixed	getFirstValue()	Get the value of the first (or the given) column of the first row in the result.
atkStatementIterator	getIterator()	Returns an iterator for iterating over the result rows for this statement.
string	getQuery()	Returns the query on which this statement is based.
void	reset()	Resets this statement so that it can be re-used again.
void	rewind()	Moves the cursor back to the beginning of the result set.
void	_close()	Frees up all resources for this statement. The statement cannot be re-used anymore.
void	_execute()	Executes the statement using the given bind parameters.
array	_fetch()	Fetches the next row from the result set.
void	_getAffectedRowCount()	Returns the number of affected rows in case of an INSERT, UPDATE or DELETE query. Called immediatly after atkStatement::_execute().
array	_getBindPositions()	Returns the positions for the bind parameters in the query.
array	_getLatestParams()	Get latest execution parameters.
string	_getParsedQuery()	Returns the parsed query for this statement (e.g. named bind parameters are replaced by anonymous bind parameters).
void	_parse()	Parses the query. Named bind parameters are replaced by anonymous bind parameters and the positions of the different named/anonymous bind parameters are made available for later use.
void	_prepare()	Prepares the statement for execution.
void	_reset()	Resets the statement so that it can be re-used again.
void	_validateParams()	Validates if all bind parameters are supplied.

[ Top ]

Properties

array $m_bindPositions [line 69]

Positions of bind parameters.

API Tags:

Access:

private

[ Top ]

array $m_latestParams = array() [line 83]

Latest parameters supplied to the execute() method.

API Tags:

Access:

private

[ Top ]

string $m_parsedQuery [line 62]

Parsed SQL query.

API Tags:

Access:

private

[ Top ]

int $m_position = false [line 76]

Current row offset position.

API Tags:

Access:

private

[ Top ]

string $m_query [line 55]

(Original) SQL query.

API Tags:

Access:

private

[ Top ]

Methods

Constructor __construct [line 91]

atkStatement __construct(
atkDb
$db, string
$query 
)

Constructs a new statement for the given query.

Parameters:

atkDb	$db:	database instance
string	$query:	SQL query

API Tags:

Access:

public

[ Top ]

Destructor __destruct [line 102]

void __destruct(
)

Destructor.

API Tags:

Access:

public

[ Top ]

close [line 225]

void close(
)

Close this statement.

Frees all resources after which this statement cannot be used anymore. If you want to re-use the statement, use the atkStatement::reset() method.

API Tags:

Access:

public

[ Top ]

execute [line 275]

void execute(
[
$params = array()] 
)

Executes the statement.

Parameters:

array

$params:

bind parameters

API Tags:

Access:

public

[ Top ]

fetch [line 289]

mixed fetch(
)

Fetches the next row from the result set.

API Tags:

Return:	next row or false if there are no more rows
Access:	public

[ Top ]

getAffectedRowCount [line 499]

void getAffectedRowCount(
)

Returns the number of affected rows in case of an INSERT, UPDATE or DELETE query.

API Tags:

Access:

public

[ Top ]

getAllRows [line 360]

array getAllRows(
)

Get all rows for the given query.

NOTE: This is not an efficient way to retrieve records, as this will load all records into an array in memory. If you retrieve a lot of records, you are better of using atkStatement::getIterator which only retrieves one row at a time.

Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

API Tags:

Return:	rows
Access:	public

[ Top ]

getAllRowsAssoc [line 381]

array getAllRowsAssoc(
[int|string
$keyColumn = 0] 
)

Get rows in an associative array with the given column used as key for the rows.

Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

Parameters:

int|string

$keyColumn:

column index / name (default first column) to be used as key

API Tags:

Return:	rows
Access:	public

[ Top ]

getAllValues [line 454]

array getAllValues(
[int|string
$valueColumn = 0] 
)

Get an array with all the values in the specified column.

Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

Parameters:

int|string

$valueColumn:

column index / name (default first column) to be used as value

API Tags:

Return:	with values
Access:	public

[ Top ]

getAllValuesAssoc [line 477]

array getAllValuesAssoc(
[int|string
$keyColumn = 0], [int|string
$valueColumn = 1] 
)

Get rows in an associative array with the given key column used as key and the given value column used as value.

Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

Parameters:

int\|string	$keyColumn:	column index / name (default first column) to be used as key
int\|string	$valueColumn:	column index / name (default first column) to be used as value

API Tags:

Return:	rows
Access:	public

[ Top ]

getDb [line 124]

atkDb getDb(
)

Returns the database instance.

API Tags:

Return:	database instance
Access:	public

[ Top ]

getFirstRow [line 332]

array getFirstRow(
)

Returns the first row.

NOTE: Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

API Tags:

Return:	row
Access:	public

[ Top ]

getFirstValue [line 420]

mixed getFirstValue(
[int|string
$valueColumn = 0], [mixed
$fallback = null] 
)

Get the value of the first (or the given) column of the first row in the result.

NOTE: Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

Parameters:

int\|string	$valueColumn:	column index / name (default first column) to be used as value
mixed	$fallback:	fallback value if no result

API Tags:

Return:	first value
Access:	public

[ Top ]

getIterator [line 315]

atkStatementIterator getIterator(
)

Returns an iterator for iterating over the result rows for this statement.

NOTE: Depending on the database driver, using this method multiple times might result in the query to be executed multiple times.

API Tags:

Return:	iterator
Access:	public

Implementation of:

IteratorAggregate::getIterator

[ Top ]

getQuery [line 134]

string getQuery(
)

Returns the query on which this statement is based.

API Tags:

Return:	query
Access:	public

[ Top ]

reset [line 212]

void reset(
)

Resets this statement so that it can be re-used again.

API Tags:

Access:

public

[ Top ]

rewind [line 240]

void rewind(
)

Moves the cursor back to the beginning of the result set.

NOTE: Depending on the database driver, using this method might result in the query to be executed again.

API Tags:

Access:

public

Redefined in descendants as:

atkMySQLiStatement::rewind() : Moves the cursor back to the beginning of the result set.

[ Top ]

_close [line 201]

void _close(
)

Frees up all resources for this statement. The statement cannot be re-used anymore.

API Tags:

Abstract:
Access:	protected

Redefined in descendants as:

atkCompatStatement::_close() : Frees up all resources for this statement. The statement cannot be re-used anymore.
atkMySQLiStatement::_close() : Frees up all resources for this statement. The statement cannot be re-used anymore.

[ Top ]

_execute [line 183]

void _execute(
array
$params 
)

Executes the statement using the given bind parameters.

Parameters:

array

$params:

bind parameters

API Tags:

Abstract:
Access:	protected

Redefined in descendants as:

atkCompatStatement::_execute() : Executes the statement using the given bind parameters.
atkMySQLiStatement::_execute() : Executes the statement using the given bind parameters.

[ Top ]

_fetch [line 190]

array _fetch(
)

Fetches the next row from the result set.

API Tags:

Return:	next row from the result set (false if no other rows exist)
Abstract:
Access:	protected

Redefined in descendants as:

atkCompatStatement::_fetch() : Fetches the next row from the result set.
atkMySQLiStatement::_fetch() : Fetches the next row from the result set.

[ Top ]

_getAffectedRowCount [line 207]

void _getAffectedRowCount(
)

Returns the number of affected rows in case of an INSERT, UPDATE or DELETE query. Called immediatly after atkStatement::_execute().

API Tags:

Abstract:
Access:	protected

Redefined in descendants as:

atkCompatStatement::_getAffectedRowCount() : Returns the number of affected rows in case of an INSERT, UPDATE or DELETE query. Called immediatly after atkStatement::_execute().
atkMySQLiStatement::_getAffectedRowCount() : Returns the number of affected rows in case of an INSERT, UPDATE or DELETE query. Called immediatly after atkStatement::_execute().

[ Top ]

_getBindPositions [line 158]

array _getBindPositions(
)

Returns the positions for the bind parameters in the query.

The key of the array contains the character position, the value contains the bind parameter name or offset.

API Tags:

Return:	bind positions
Access:	protected

[ Top ]

_getLatestParams [line 168]

array _getLatestParams(
)

Get latest execution parameters.

API Tags:

Return:	execution parameters
Access:	protected

[ Top ]

_getParsedQuery [line 145]

string _getParsedQuery(
)

Returns the parsed query for this statement (e.g. named bind parameters are replaced by anonymous bind parameters).

API Tags:

Access:

protected

[ Top ]

_parse [line 112]

void _parse(
)

Parses the query. Named bind parameters are replaced by anonymous bind parameters and the positions of the different named/anonymous bind parameters are made available for later use.

API Tags:

Access:

protected

[ Top ]

_prepare [line 176]

void _prepare(
)

Prepares the statement for execution.

API Tags:

Abstract:
Access:	protected

Redefined in descendants as:

atkCompatStatement::_prepare() : Prepares the statement for execution.
atkMySQLiStatement::_prepare() : Prepares the statement for execution.

[ Top ]

_reset [line 195]

void _reset(
)

Resets the statement so that it can be re-used again.

API Tags:

Abstract:
Access:	protected

Redefined in descendants as:

atkCompatStatement::_reset() : Resets the statement so that it can be re-used again.
atkMySQLiStatement::_reset() : Resets the statement so that it can be re-used again.

[ Top ]

_validateParams [line 259]

void _validateParams(
array
$params 
)

Validates if all bind parameters are supplied.

Parameters:

array

$params:

bind parameters

API Tags:

Access:

protected

[ Top ]