Docs For Class GALTable

GALTable __construct(
GALDatabase
$db, string
$tableName, resource
$descriptor, [GALResultFactory
$resultFactory = false], [GALRowFactory
$rowFactory = false])

Initializes this table.

The most comfortable way to construct a table is to use the GALDatabase::table() method. All factories have to be set in the constructor and cannot be changed afterwards, because otherwise caching would be very difficult. This way it is guaranteed (provided the resultFactory and the rowFactory act properly) that only items of one kind are fetched.

Overridden in child classes as:

GALGallueTable::__construct(): Initializes $glb object variable.

GALUsers::__construct(): Initialize using GALGallery object.

GALNodes::__construct(): Initialize using GALGallery object.

GALFilms::__construct(): Initialize using GALGallery object.

GALHelps::__construct()

GALComments::__construct(): Initializes using a GALGallery object.

GALImages::__construct(): Initialize using GALGallery object.

GALSeriesT::__construct()

GALGroups::__construct(): Initializes using a GALGallery object.

GALInstances::__construct(): Initialize using GALGallery object.

GALLogins::__construct()

GALJobs::__construct(): Initialize using GALGallery object.

GALCategories::__construct(): Initialize using GALGallery object.

GALTokens::__construct()

Parameters:

GALDatabase	$db	The database connection.
string	$tableName	The table's name.
resource	$descriptor	The result of GALDatabase::list_fields() or mysql_list_fields().
GALResultFactory	$resultFactory	A substitute result factory. If set, it is used instead of the default factory
GALRowFactory	$rowFactory	A substitute row factory. If set, it is used instead of the default factory

[ Top ]

void __destruct(
)

Destructs all rows stored in $rows.

It makes use of recurse_rows().

[ Top ]

void buildResult(
resource
$result)

Implements the GALResultFactory interface.

Overridden in child classes as:

GALUsers::buildResult(): Creates iterator on mysql result resource.

GALNodes::buildResult(): Creates iterator on mysql result resource.

GALFilms::buildResult(): Creates a GALFilmIterator.

GALHelps::buildResult(): Creates a GALHelpIterator.

GALComments::buildResult(): Creates a GALCommentIterator.

GALImages::buildResult(): Creates a GALImageIterator.

GALSeriesT::buildResult()

GALGroups::buildResult(): Creates a GALGroupIterator.

GALInstances::buildResult(): Creates iterator on mysql result resource.

GALLogins::buildResult(): Creates iterator on mysql result resource.

GALJobs::buildResult(): Creates iterator on mysql result resource.

GALCategories::buildResult(): Creates a GALCategoryIterator.

GALTokens::buildResult(): Creates iterator on mysql result resource.

Implementation of:

GALResultFactory::buildResult()

Parameters:

resource

$result

[ Top ]

void compareExpression(
string
$field, string
$operator, string
$value)

Factory for GALExpressionCompare objects.

Parameters:

string	$field	The name of the compared field.
string	$operator	One of "=", "!=", ">", ">=", "<" or "<=".
string	$value	The value the field is compared with.

[ Top ]

bool containsKeyFields(
array
$fields)

Checks if the specified fields contains a field that belongs to the primary key.

Tags:

return:	TRUE if the specified fields contain a field that belongs to the primary key, FALSE otherwise.
access:	protected
throws:	Exception If $fields isn't an array.

Parameters:

array

$fields

An array with field names as strings.

[ Top ]

int count(
[GALExpression
$expr = true], [string
$additional = ""])

Count rows that match the given GALExpression.

This method calls rawLoad() with

"WHERE ".$expr->__toString()." $additional"

as argument. Because PHP 5 doesn't support objects as default argument, TRUE is default instead of GALExpressionTRUE.

Tags:

return:	The number of rows.
throws:	GAL_Edatabase If the query fails or the arguments don't match the required type.

Parameters:

GALExpression	$expr	A SQL logical expression, or the boolean TRUE as alias of GALExpressionTRUE.
string	$additional	An arbitrary string that is appended to the query.

[ Top ]

int countFields(
)

Returns the number of fields contained in a result.

Wrapper for GALResult::countFields().

Tags:

return:	$descriptor->countFields()
see:	GALDesc::countFields()

Implementation of:

GALDesc::countFields(): Returns the number of fields contained in a result.

[ Top ]

void delete(
array
$key)

Deletes the row identified by $key from the database.

This method deletes a single row from the database and marks it as deleted in $rows. The $key parameter must contain all fields of the primary key and no other fields.

Tags:

throws:

GAL_EDatabase If the submitted key is invalid.

Parameters:

array

$key

Associative array where the fields of the primary key are the keys and the key values are the values.

[ Top ]

int extendedCount(
string
$join, GALExpression
$expr, [mixed
$order = ""], [string
$limit = ""], [string
$additional = ""])

Template for complex count queries.

This method allows to build a more complex SQL query from the submitted pieces. This method is introduced because in many cases JOIN statements, expressions, ORDER statements and LIMIT statements are created in different places. This method provides a shortcut to put them all together. Additionally, this method allows to introduce new ways to specify such a statement without changing much code - just redefine it in descending classes or change it in this place. Theoretically the ORDER statement is senseless, but it remains to be compatible with extendedLoad() regarding the parameters.

Tags:

return:	The number of rows.
throws:	GAL_Edatabase If the query fails.

Parameters:

string	$join	A JOIN expression that is passed unfiltered to the database.
GALExpression	$expr	A SQL logical expression, see GALExpression.
mixed	$order	Ignored
string	$limit	A LIMIT expression that is passed unfiltered to the database.
string	$additional	Additional SQL fragment that is appended to the query.

[ Top ]

GALTableIterator extendedLoad(
string
$join, GALExpression
$expr, [mixed
$order = ""], [string
$limit = ""], [string
$additional = ""])

Template for complex queries.

This method allows to build a more complex SQL query from the submitted pieces. This method is introduced because in many cases JOIN statements, expressions, ORDER statements and LIMIT statements are created in different places. This method provides a shortcut to put them all together. Additionally, this method allows to introduce new ways to specify such a statement without changing much code - just redefine it in descending classes or change it in this place.

Tags:

return:	The result of the query.
throws:	GAL_Edatabase If the query fails.

Parameters:

string	$join	A JOIN expression that is passed unfiltered to the database.
GALExpression	$expr	A SQL logical expression, see GALExpression.
mixed	$order	A string that is passed unfiltered to the database, or an instance of GALOrder.
string	$limit	A LIMIT expression that is passed unfiltered to the database.
string	$additional	Additional SQL fragment that is appended to the query.

[ Top ]

bool fullKey(
array
$keys)

Checks if the specified fields in $keys are the full primary key.

Tags:

return:	TRUE if the specified fields are the primary key, FALSE if fields are missing or fields don't belong to the primary key.
access:	protected
throws:	Exception If $keys isn't an array.

Parameters:

array

$keys

An array with field names as strings.

[ Top ]

array getFields(
)

Returns all fields contained in this result.

Tags:

return:	$descriptor->getFields()
throws:	GAL_EDatabase
see:	GALDesc::getFields()

Implementation of:

GALDesc::getFields(): Returns all fields contained in a result.

[ Top ]

string getFlags(
string
$field)

Gets the flags of the given field.

Wrapper for GALResult::getFlags().

Tags:

return:	$descriptor->getFlags()
throws:	GAL_EDatabase
todo:	Make it possible to inherit documentation from interfaces (not only from classes).
see:	GALDesc::getFlags()

Implementation of:

GALDesc::getFlags(): Gets the flags of the given field.

Parameters:

string

$field

A field name.

[ Top ]

GALTableRow getIfRegistered(
array
&$keys)

Return the row with the submitted primary key values, if it has been registered before.

Tags:

return:

The row if it's entry in $rows is existing, TRUE if the row was deleted, FALSE if it wasn't registered.

Parameters:

array

&$keys

Associative array with the primary key where the field names are the keys and the field values are the values.

[ Top ]

int getLength(
string
$field)

Gets the length of the given field.

Wrapper for GALResult::getLength().

Tags:

return:	$descriptor->getLength()
throws:	GAL_EDatabase
see:	GALDesc::getLength()

Implementation of:

GALDesc::getLength(): Gets the length of the given field.

Parameters:

string

$field

A field name.

[ Top ]

string getName(
)

Returns this table's name.

[ Top ]

GALTable getParent(
)

Returns a reference to this table.

A GALTable is a top level element, so this method returns a reference to itself.

Tags:

see:

GALDesc::getParent()

Implementation of:

GALDesc::getParent(): Return the top level parent of an entity.

[ Top ]

array getPrimaryKey(
)

Returns the primary key of this table.

Tags:

return:

Array with the field names of the primary key.

[ Top ]

GALResultFactory getResultFactory(
)

Returns the factory to construct results.

[ Top ]

GALRowFactory getRowFactory(
)

Returns the factory to construct rows.

[ Top ]

string getTable(
string
$field)

Gets the name of the table the given field is contained in.

Wrapper for GALResult::getTable().

Tags:

return:	$descriptor->getTable()
throws:	GAL_EDatabase
see:	GALDesc::getTable()

Implementation of:

GALDesc::getTable(): Gets the name of the table the given field is contained in.

Parameters:

string

$field

A field name.

[ Top ]

string getType(
string
$field)

Gets the type of the given field.

Wrapper for GALResult::getType().

Tags:

return:	$descriptor->getType()
throws:	GAL_EDatabase
see:	GALDesc::getType()

Implementation of:

GALDesc::getType(): Gets the type of the given field.

Parameters:

string

$field

The name of a field.

[ Top ]

int insert(
array
$data)

Inserts a row into this table.

unfortunately this method cannot return the inserted data as row object, because data might be changed (default values, AUTO_INCREMENT), and keys are possibly created by an AUTO_INCREMENT field, so in some cases it is difficult to reconstruct the inserted data. >:-( (multiple AUTO_INCREMENTs and so on) To make things easier though, this function returns the value of mysql_insert_id().

Tags:

return:

$db->last_insert_id().

Parameters:

array

$data

An associative array where the field names are the keys and the new field values are the values.

[ Top ]

void insertMultiple(
array
$fields, array
$data)

Inserts multiple rows into the database.

Example how to insert two rows into the table `users` wich contains the fields `name`, `ID`, `email`:

$table = $db->table('users');
$fields = array('name', 'ID', 'email');
$values = array(
array('Kurt', 4, 'kurt@example.com'),
array('Ernst', 5, 'ernst@example.com')
);
$table->insertMultiple($fields, $values);

Field and value are mapped together by their position in the arrays.

Tags:

throws:	GAL_Edatabase If the fields are invalid or the query fails.
throws:	Exception If the arguments have a wrong format.

Parameters:

array	$fields	Array of field names.
array	$data	Array of arrays of new field values.

[ Top ]

bool isField(
string
$field)

Checks if the given field is contained in a result.

Wrapper for GALResult::isField().

Tags:

return:	$descriptor->isField()
see:	GALDesc::isField()

Implementation of:

GALDesc::isField(): Checks if the given field is contained in a result.

Parameters:

string

$field

The name of a field.

[ Top ]

GALTableIterator load(
[GALExpression
$expr = true], [string
$additional = ""])

Load rows that match the given GALExpression.

This method calls rawQuery() with

"WHERE ".$expr->__toString()." $additional"

as argument. Because PHP 5 doesn't support objects as default argument, TRUE is default instead of GALExpressionTRUE.

Tags:

return:	The result of the query
todo:	Find a possibility to specify objects (or new class()) as default value, find a way to build constant objects.

Parameters:

GALExpression	$expr	A SQL logical expression, or the boolean TRUE as alias of GALExpressionTRUE.
string	$additional	An arbitrary string that is appended to the query.

[ Top ]

int rawCount(
[string
$what = ""])

Counts rows from this table.

This method submits "SELECT COUNT(`$table`.*) AS `count` FROM `$table` $what" to the database, where $table is the name of this table. Note that there's no filtering of $what, so be careful! This method allows full flexibility in the selection of what is counted, e.g. complex joins, SQL functions and so on.

Tags:

return:	The number of rows.
throws:	GAL_EDatabase If the query fails.

Parameters:

string

$what

Part of a SQL query.

[ Top ]

GALTableIterator rawLoad(
[string
$what = ""])

Loads rows from this table.

This method submits "SELECT `$table`.* FROM `$table` $what" to the database, where $table is the name of this table. Note that there's no filtering of $what, so be careful! This method allows full flexibility in the selection of what is to be fetched, e.g. complex joins, SQL functions and so on. It is final to make sure that all fetched items are registered: GALTableIterator::fetch() is final, too; therefore it is impossible to circumvent the registration

Tags:

return:	The result of the query.
throws:	GAL_EDatabase If the query fails.

Parameters:

string

$what

Part of a SQL query.

[ Top ]

GALTableRow register(
GALTableRow
$row)

Registers the specified row or returns an already registered row.

This method's task is to make sure that for one row in the database only one GALTableRow object exists. Therefor after constructing a GALTableRow in GALTableIterator::fetch(), it is registered here. This method checks if a row with the same primary key values was registered before. If such a row doesn't exist, this method creates a new entry in $rows and returns the $row parameter. If such a row exists, the row registered before is returned and the row passed in $row is destroyed. If the row in $rows is marked as deleted (this happens if a row is deleted from the database in delete(), but the result of a query is still existing), the submitted row object is destroyed and the destroyed row is returned.

Tags:

return:	The submitted row or a row that has been registered before.
throws:	GAL_EDatabase If the submitted row belongs to another table.

Parameters:

GALTableRow

$row

The row to register.

[ Top ]

bool registered(
GALTableRow
$row)

Checks if the specified row is already registered.

Tags:

return:	TRUE if the row has been registered, FALSE otherwise.
throws:	GAL_EDatabase If the submitted row belongs to another table.

[ Top ]

GALTableRow row(
array
$key)

Fetches a row matching the given key from the database.

Tags:

return:	The row that matches if existing; FALSE if the row is not existing.
throws:	GAL_EDatabase If the key is invalid or the query fails.

Parameters:

array

$key

Associative array where the fields of the primary key are the array keys and the field values are the values.

[ Top ]

void setRegistered(
array
&$keys, mixed
$value)

Set the entry in $rows specified by &$keys to the specified value.

This is for internal purposes and doesn't perform any consistency checks. You can easily mangle the $rows property by using this function!

Tags:

access:

protected

Parameters:

array	&$keys	Associative array with the primary key where the field names are the keys and the field values are the values.
mixed	$value	The value the entry is to be set to.

[ Top ]

void stripKeys(
array
&$data)

Removes all fields from the submitted data which belong to the primary key.

Tags:

access:

protected

Parameters:

array

&$data

Associative array where the field names are keys.

[ Top ]

void unregister(
GALTableRow
$row)

Removes a registered row.

This method is used to remove a row from $rows. If you want to replace a row, you have to delete it, and before inserting the new row you have to unregister the new row because otherwise registering the new row would fail due to the old row remaining as marked 'dead'.

Tags:

throws:

GAL_EDatabase If the submitted row belongs to another table.

Parameters:

GALTableRow

$row

The row to unregister.

[ Top ]

void updateRow(
array
$keys, array
$data)

Sets the fields of the specified row to the specified values.

This method builds an UPDATE statement and submits it to the database. A row is identified by it's primary key, and changing the fields of the primary key is not supported. If you want to change the primary key, the best way is to delete the row and insert it with the new key.

Parameters:

array	$keys	Associative array where the fields of the primary key are the keys and their values are the values.
array	$data	Associative array where the field names are the keys and their new values are the values.

[ Top ]

bool validFields(
array
$fields)

Checks if all the field names submitted in $fields are valid.

Tags:

return:	TRUE if all fields are valid, FALSE otherwise.
throws:	Exception If $fields isn't an array.

Parameters:

array

$fields

An array with field names as strings.

[ Top ]

Class: GALTable

Class Overview

Author(s):

Variables

Methods

Child classes:

Class Details

Tags:

Class Variables

$db =

Tags:

$descriptor =

Tags:

$primary = array()

Tags:

$resultFactory =

Tags:

$rowFactory =

Tags:

$rows = array()

Tags:

$tableName =

Tags:

Class Methods

constructor __construct [line 758]

Parameters:

destructor __destruct [line 812]

method buildResult [line 1335]

Parameters:

method compareExpression [line 1328]

Parameters:

method containsKeyFields [line 948]

Tags:

Parameters:

method count [line 1160]

Tags:

Parameters:

method countFields [line 1420]

Tags:

method delete [line 1302]

Tags:

Parameters:

method extendedCount [line 1188]

Tags:

Parameters:

method extendedLoad [line 1118]

Tags:

Parameters:

method fullKey [line 978]

Tags:

Parameters:

method getFields [line 1410]

Tags:

method getFlags [line 1364]

Tags:

Parameters:

method getIfRegistered [line 895]

Tags:

Parameters:

method getLength [line 1388]

Tags:

Parameters:

method getName [line 787]

method getParent [line 1441]

Tags:

method getPrimaryKey [line 1008]

Tags:

method getResultFactory [line 1342]

method getRowFactory [line 1350]

method getTable [line 1400]

Tags:

Parameters:

method getType [line 1376]

Tags:

Parameters:

method insert [line 1227]

Tags:

Parameters:

method insertMultiple [line 1250]

Tags: