spunQ_SelectQuery Class Reference

A generic select query. More...

Inheritance diagram for spunQ_SelectQuery:

List of all members.

Public Member Functions

execute ($parameters=array(), $connection=NULL)

Executes this query on given database connection.

count ($parameters=array(), $connection=NULL)

Returns number of objects the query would match.

setPage ($page)

Convenience function that will set $offset for a page number.

setId ($id)

Setter for the id.

getId ()

Getter for the id.

store ()

Will either insert or update a row in the database.

insert ()

Will insert this object into the database.

delete ()

Will remove this object from the database.

update ()

Will Update the members of this object in the database.

assureExists ()

Throws an exception if this object does not exist in the database.

setConnection (spunQ_IDatabaseConnection $connection)

Sets the connection that is persisting this object.

getConnection ()

Gets the connection that is persisting this object.

handleSet ($memberName, $arguments, $functionName)

Overridden to mark the member as locally modified.

_loadRemoteValues (array $values, $checkValues=true)

Loads members that have been fetched with a query.

_invalidateRemoteValues (array $memberNames)

_getDisplayString ()

Gets the human readable object name of this object.

_remoteValueLoaded ($memberName)

Cheks whether a remote value for given member was loaded.

referencingObjects ($otherType, $otherMember, $order=NULL, $limit=NULL)

Gets the objects having the current one associated.

referencingObjectIds ($otherType, $otherMember, $order=NULL, $limit=NULL)

Gets the objects having the current one associated.

countReferencingObjects ($otherType, $otherMember)

Counts the objects having the current one associated.

__call ($functionName, $arguments)

Overloaded to provide automatic getters and setters.

__sleep ()

Replaces $_type with the type's name.

_verifyMembers ($omittedMembers=array(), $throwException=true)

Verifies that all members are valid.

_getMember ($name)

Gets the value of a member of this object.

_setMember ($name, $value)

Sets the value of a member of this object.

_getType ($throwException=true)

Gets the type of this object.

Static Public Member Functions

static insertMultiple (array $objects, spunQ_IDatabaseConnection $connection=NULL)

Updates multiple objects at once.

static updateMultiple (array $objects)

Updates multiple objects at once.

static deleteMultiple (array $objects)

Deletes multiple objects at once.

static sortByDisplayString ($objects)

Sorts storable objects by their object names.

static valueByProperty ($value, $path)

Transforms a value using a property path.

static propertyOfValue ($value, $property)

Gets a single property of a value.

Public Attributes

const RETURN_OBJECTS = 1

Query will return spunQ_StorableObjects.

const RETURN_ARRAY = 2

Query will return a [multi-]array containing requested fields.

const RETURN_SINGLE_PROPERTY = 4

Query will return a array containing just one property per result.

Protected Member Functions

loadMember ($memberName)

Fetches the value of a member of this object from the database.

handleGet ($memberName, $arguments, $functionName)

Overridden to possibly retrieve the value from the database.

handleAdd ($memberName, $arguments, $functionName)

Overridden to fetch data before manipulation.

handleRemove ($memberName, $arguments, $functionName)

Overridden to fetch data before manipulation.

handleGetUntranslated ($memberName, $arguments, $functionName)

Overridden to fetch data.

handleGetFromArray ($memberName, $arguments, $functionName)

Overridden to fetch data.

initLocalizedMember ($memberName)

Makes sure a localized member contains a spunQ_Map.

Static Protected Member Functions

static loadInjectedMember ($connection, spunQ_InjectedMember $injectedMember)

Loads injected members for several objects.

Protected Attributes

$limit = NULL

The number of entries to select at most.

$offset = NULL

The number of entries to skip.

$orders = array()

The property by which the result set will be ordered.

$type

The type to fetch.

$properties = array()

The properties to select.

$conditions = array()

Conditions to this query.

$returnType = self::RETURN_OBJECTS

Definition of the return type.

$id

The unique id of this object.

$remoteValues = array()

Members that have been loaded from the database.

$locallyModifiedMembers = array()

$connection = NULL

The connection that is persisting this object.

$_type

The actual type of this object.

Detailed Description

A generic select query.

Developer log entry:

Necdet Can Atesman (2009-07-27): How do we select collections? Possible solutions:

Forbid selecting collections: This was the approach in the old version. The usage was unconventional, thus not very user-friendly, there were two query types (ObjectRetrieval and CollectionRetrieval) and this solution is too specific to sql databases.
Select the id of the collection table: Trivial implementation, but we would need to create new functions for retrieving these values. Furthermore, these values should not have an id outside this package.
The only remaining option is to fetch whatever we can. Collections are processed recursively and returned in the correct data type (array/map). The user of the API is free to add transformers to his properties to fetch sub-sets. This will take some effort to implement, but should provide the most intuitive return value. Let's do it.

Definition at line 23 of file SelectQuery.type.php.

Member Function Documentation

spunQ_DataObject::__call	(	$	functionName,
		$	arguments
	)			`[inherited]`

Overloaded to provide automatic getters and setters.

Parameters:

	$functionName	The function that was called.
	$arguments	Array containing the arguments that were passed to the function.

Exceptions:

spunQ_BadArgumentCountError

Definition at line 148 of file DataObject.type.php.

spunQ_DataObject::__sleep ( ) [inherited]

Replaces $_type with the type's name.

Returns:: array<string>

Reimplemented in spunQ_ArrayType, spunQ_MapType, and spunQ_SetType.

Definition at line 178 of file DataObject.type.php.

spunQ_StorableObject::_getDisplayString ( ) [inherited]

Gets the human readable object name of this object.

Returns:: string

Reimplemented in spunQ_LoginUser, and spunQ_User.

Definition at line 427 of file StorableObject.type.php.

spunQ_DataObject::_getMember ( $ name ) [inherited]

Gets the value of a member of this object.

Will check if the object has a getter for the member and will use that method for getting the value. Otherwise, the value of the object member is returned.

Parameters:

$name

The name of the member.

Returns:: any Whatever type the member has.

Definition at line 478 of file DataObject.type.php.

spunQ_DataObject::_getType ( $ throwException = true ) [inherited]

Gets the type of this object.

Returns:: spunQ_Type

Definition at line 507 of file DataObject.type.php.

spunQ_StorableObject::_loadRemoteValues	(	array $	values,
		$	checkValues = `true`
	)			`[inherited]`

Loads members that have been fetched with a query.

This function is only intended to process the objects own members. It will handle concatenated member names incorrectly (i.e. origin.country.name will not work as expected.) This behaviour is expected to change in future releases, though.

Parameters:

	$values	An entry in an array that was returned by spunQ_ISelectQuery::execute() with a return mode of RETURN_ARRAY.
	$checkValues	Whether the values should be run through the check() functions of the members types. This value will be ignored in deployment mode, so it is generally advised to leave this as-is. Its purpose is to speed up the framework in development mode.

Returns:: spunQ_StorableObject $this

Definition at line 394 of file StorableObject.type.php.

spunQ_StorableObject::_remoteValueLoaded ( $ memberName ) [inherited]

Cheks whether a remote value for given member was loaded.

A remote value can only be loaded using _loadRemoteValues().

Returns:: boolean

Definition at line 453 of file StorableObject.type.php.

spunQ_DataObject::_setMember	(	$	name,
		$	value
	)			`[inherited]`

Sets the value of a member of this object.

Will check if the object has a setter for the member and will use that method for setting the value. Otherwise, the object member is set directly.

Parameters:

	$name	The name of the member.
	$value	The value to set it to.

Returns:: spunQ_DataObject $this

Definition at line 495 of file DataObject.type.php.

spunQ_DataObject::_verifyMembers	(	$	omittedMembers = `array()`,
		$	throwException = `true`
	)			`[inherited]`

Verifies that all members are valid.

This function is called from various modules prior to critical actions requiring a complete object - like inserting into a database.

Parameters:

	$omittedMembers	Do not perform checks on these member names.
	$throwException	Whether an exception should be thrown if a member does not have a valid value.

Returns:: boolean

Exceptions:

spunQ_IllegalValueException

Definition at line 458 of file DataObject.type.php.

spunQ_StorableObject::assureExists ( ) [inherited]

Throws an exception if this object does not exist in the database.

Will try to fetch some members for this object. Note that one should not rely on the result of this method. The entry in the database could be deleted even before this function returns (a typical race condition).

Returns:: spunQ.db.StorableObject $this

Todo:: implement me

Definition at line 336 of file StorableObject.type.php.

spunQ_SelectQuery::count	(	$	parameters = `array()`,
		$	connection = `NULL`
	)

Returns number of objects the query would match.

Returns:: integer

Definition at line 110 of file SelectQuery.type.php.

spunQ_StorableObject::delete ( ) [inherited]

Will remove this object from the database.

Returns:: spunQ.db.StorableObject $this

Definition at line 294 of file StorableObject.type.php.

static spunQ_StorableObject::deleteMultiple ( array $ objects ) [static, inherited]

Deletes multiple objects at once.

Using this function instead of calling delete() on all objects can lead to a performance increase.

Parameters:

$objects

The objects to delete.

Returns:: void

Exceptions:

spunQ_InvalidArgumentError

If the objects are managed by different connections.

Definition at line 107 of file StorableObject.type.php.

spunQ_SelectQuery::execute	(	$	parameters = `array()`,
		$	connection = `NULL`
	)

Executes this query on given database connection.

Parameters:

$connection

The connection to issue this query on.

Returns:: any If $this->returnAffectedIds is true, this will return an array of integers representing the ids of the affected objects. Otherwise the return value will be NULL.

Definition at line 99 of file SelectQuery.type.php.

spunQ_StorableObject::getConnection ( ) [inherited]

Gets the connection that is persisting this object.

Returns:: spunQ_IDatabaseConnection

Definition at line 364 of file StorableObject.type.php.

spunQ_StorableObject::getId ( ) [inherited]

Getter for the id.

Returns:: integer

Definition at line 265 of file StorableObject.type.php.

spunQ_DataObject::initLocalizedMember ( $ memberName ) [protected, inherited]

Makes sure a localized member contains a spunQ_Map.

Parameters:

$memberName The name of the member. This member must have the option 'localized'.

Returns:: void

Definition at line 245 of file DataObject.type.php.

spunQ_StorableObject::insert ( ) [inherited]

Will insert this object into the database.

Returns:: spunQ.db.StorableObject $this

Definition at line 285 of file StorableObject.type.php.

static spunQ_StorableObject::insertMultiple	(	array $	objects,
		spunQ_IDatabaseConnection $	connection = `NULL`
	)			`[static, inherited]`

Updates multiple objects at once.

Using this function instead of calling insert() on all objects can lead to a performance increase.
WARNING: The objects passed as first parameter must have the same type. WARNING: This function will set the objects' $connection attribute to the given value.

Parameters:

	$objects	The objects to insert.
	$connection	The database connection to use for persisting the objects. The default connection will be used if omitted.

Returns:: void

Definition at line 37 of file StorableObject.type.php.

static spunQ_StorableObject::loadInjectedMember	(	$	connection,
		spunQ_InjectedMember $	injectedMember
	)			`[static, protected, inherited]`

Loads injected members for several objects.

Parameters:

	$connection	Connection to use for queries.
	$injectedMember	The member to load. return void

Definition at line 181 of file StorableObject.type.php.

spunQ_StorableObject::loadMember ( $ memberName ) [protected, inherited]

Fetches the value of a member of this object from the database.

Parameters:

$memberName

The name of the member to load.

Returns:: spunQ.db.StorableObject $this

Definition at line 491 of file StorableObject.type.php.

static spunQ_DataObject::propertyOfValue	(	$	value,
		$	property
	)			`[static, inherited]`

Gets a single property of a value.

See also:: valueByProperty()

Parameters:

	$value	The value to fetch property for.
	$property	The property to fetch.

Returns:: any

Definition at line 74 of file DataObject.type.php.

spunQ_StorableObject::setConnection ( spunQ_IDatabaseConnection $ connection ) [inherited]

Sets the connection that is persisting this object.

Parameters:

$connection

The connection managing $this.

Returns:: spunQ_StorableObject $this

Definition at line 349 of file StorableObject.type.php.

spunQ_StorableObject::setId ( $ id ) [inherited]

Setter for the id.

This function is called very frequently - this implemetation is in fact an optimization (otherwise we'd run through spunQ_DataObject::__call() each time).

Returns:: spunQ_StorableObject $this

Definition at line 256 of file StorableObject.type.php.

spunQ_SelectQuery::setPage ( $ page )

Convenience function that will set $offset for a page number.

The limit must already be set prior to calling this function and modifying the limit afterwards will yield an undefined offset.

Parameters:

$page

The page number to fetch.

Returns:: spunQ_SelectQuery $this

Exceptions:

spunQ_InvalidArgumentError

If $limit is NULL

Definition at line 125 of file SelectQuery.type.php.

static spunQ_StorableObject::sortByDisplayString ( $ objects ) [static, inherited]

Sorts storable objects by their object names.

Parameters:

$objects

an array of storable objects.

Returns:: string

Definition at line 158 of file StorableObject.type.php.

spunQ_StorableObject::store ( ) [inherited]

Will either insert or update a row in the database.

Returns:: spunQ.db.StorableObject $this

Definition at line 273 of file StorableObject.type.php.

spunQ_StorableObject::update ( ) [inherited]

Will Update the members of this object in the database.

Returns:: spunQ.db.StorableObject $this

Definition at line 303 of file StorableObject.type.php.

static spunQ_StorableObject::updateMultiple ( array $ objects ) [static, inherited]

Updates multiple objects at once.

Using this function instead of calling update() on all objects can lead to a performance increase.

Parameters:

$objects

The objects to update.

Returns:: void

Exceptions:

spunQ_InvalidArgumentError

If the objects are managed by different connections.

Definition at line 77 of file StorableObject.type.php.

static spunQ_DataObject::valueByProperty	(	$	value,
		$	path
	)			`[static, inherited]`

Transforms a value using a property path.

Some types are considered to have properties within spunQ. These properties can be referred to using property path definitions. The most simple case for properties is the user type, for which every member is considered a property. Concatenations of these paths with dots as separators are called property path. The list of all users in the primary group of a given user can be described using this method in a string: 'primaryGroup.users'.
Different types have different properties:

UserType: As already mentioned, every member of a user type is a property of an object of that type.
Map:
- _keys: An array of the keys of the map.
- _values: An array of the values of the map. Note that _keys and _values are guaranteed to return arrays where the index of a key matches the index of its value in the according result.
- _key: The first entry of the _keys property. This is handy for referencing the key of single key/value pairs.
- _value: The first entry of the _values property.
- _count: The amount of items in the map.
Array:
- _keys: The array of keys of the array. Note that the difference between arrays and maps in spunQ is that arrays are always numerically indexed! So this will always return an array containing a range of integers.
- _values: Array of values in this array. This essentially returns the array as-is and is a NOOP.
- _key: The first entry of the _keys property.
- _value: The first entry of the _values property.
- _count: The amount of items in the array.
String:
- _length: The length of the string.

Parameters:

	$value	The value to transform
	$path	The property path to use for the transformation. This can either be a string as described, or an array, each entry holding a property name.

Returns:: any The described value.

Todo:: refactor

Definition at line 54 of file DataObject.type.php.

Member Data Documentation

spunQ_DataObject::$_type [protected, inherited]

The actual type of this object.

Type:: spunQ.Type

Definition at line 129 of file DataObject.type.php.

spunQ_SelectQuery::$conditions = array() [protected]

Conditions to this query.

Array of PL strings. All conditions will be grouped with AND.

Type:: array<string>

Definition at line 80 of file SelectQuery.type.php.

spunQ_StorableObject::$connection = NULL [protected, inherited]

The connection that is persisting this object.

spunQ_IDatabaseConnection

Definition at line 247 of file StorableObject.type.php.

spunQ_StorableObject::$id [protected, inherited]

The unique id of this object.

Having a base class for all storable objects which holds an id has an important side effect: The id is unique across all tables. integer

Definition at line 228 of file StorableObject.type.php.

spunQ_SelectQuery::$limit = NULL [protected]

The number of entries to select at most.

Type:: integer

Definition at line 46 of file SelectQuery.type.php.

spunQ_SelectQuery::$offset = NULL [protected]

The number of entries to skip.

Type:: integer

Definition at line 53 of file SelectQuery.type.php.

spunQ_SelectQuery::$orders = array() [protected]

The property by which the result set will be ordered.

Type:: array<string>

Definition at line 59 of file SelectQuery.type.php.

spunQ_SelectQuery::$properties = array() [protected]

The properties to select.

If the $returnType is RETURN_OBJECTS, this will define the properties to cache.

Type:: array<string>

Definition at line 73 of file SelectQuery.type.php.

spunQ_StorableObject::$remoteValues = array() [protected, inherited]

Members that have been loaded from the database.

map<string,any>

Definition at line 235 of file StorableObject.type.php.

spunQ_SelectQuery::$returnType = self::RETURN_OBJECTS [protected]

Definition of the return type.

Either of the RETURN_* constants.

Type:: integer

Definition at line 89 of file SelectQuery.type.php.

spunQ_SelectQuery::$type [protected]

The type to fetch.

Type:: string

Definition at line 65 of file SelectQuery.type.php.

const spunQ_SelectQuery::RETURN_SINGLE_PROPERTY = 4

Query will return a array containing just one property per result.

Can only be set if $properties contains a single property.

Definition at line 39 of file SelectQuery.type.php.

The documentation for this class was generated from the following file:

SelectQuery.type.php


Public Member Functions
	execute ($parameters=array(), $connection=NULL)
	Executes this query on given database connection.
	count ($parameters=array(), $connection=NULL)
	Returns number of objects the query would match.
	setPage ($page)
	Convenience function that will set $offset for a page number.
	setId ($id)
	Setter for the id.
	getId ()
	Getter for the id.
	store ()
	Will either insert or update a row in the database.
	insert ()
	Will insert this object into the database.
	delete ()
	Will remove this object from the database.
	update ()
	Will Update the members of this object in the database.
	assureExists ()
	Throws an exception if this object does not exist in the database.
	setConnection (spunQ_IDatabaseConnection $connection)
	Sets the connection that is persisting this object.
	getConnection ()
	Gets the connection that is persisting this object.
	handleSet ($memberName, $arguments, $functionName)
	Overridden to mark the member as locally modified.
	_loadRemoteValues (array $values, $checkValues=true)
	Loads members that have been fetched with a query.
	_invalidateRemoteValues (array $memberNames)
	_getDisplayString ()
	Gets the human readable object name of this object.
	_remoteValueLoaded ($memberName)
	Cheks whether a remote value for given member was loaded.
	referencingObjects ($otherType, $otherMember, $order=NULL, $limit=NULL)
	Gets the objects having the current one associated.
	referencingObjectIds ($otherType, $otherMember, $order=NULL, $limit=NULL)
	Gets the objects having the current one associated.
	countReferencingObjects ($otherType, $otherMember)
	Counts the objects having the current one associated.
	__call ($functionName, $arguments)
	Overloaded to provide automatic getters and setters.
	__sleep ()
	Replaces $_type with the type's name.
	_verifyMembers ($omittedMembers=array(), $throwException=true)
	Verifies that all members are valid.
	_getMember ($name)
	Gets the value of a member of this object.
	_setMember ($name, $value)
	Sets the value of a member of this object.
	_getType ($throwException=true)
	Gets the type of this object.
Static Public Member Functions
static	insertMultiple (array $objects, spunQ_IDatabaseConnection $connection=NULL)
	Updates multiple objects at once.
static	updateMultiple (array $objects)
	Updates multiple objects at once.
static	deleteMultiple (array $objects)
	Deletes multiple objects at once.
static	sortByDisplayString ($objects)
	Sorts storable objects by their object names.
static	valueByProperty ($value, $path)
	Transforms a value using a property path.
static	propertyOfValue ($value, $property)
	Gets a single property of a value.
Public Attributes
const	RETURN_OBJECTS = 1
	Query will return spunQ_StorableObjects.
const	RETURN_ARRAY = 2
	Query will return a [multi-]array containing requested fields.
const	RETURN_SINGLE_PROPERTY = 4
	Query will return a array containing just one property per result.
Protected Member Functions
	loadMember ($memberName)
	Fetches the value of a member of this object from the database.
	handleGet ($memberName, $arguments, $functionName)
	Overridden to possibly retrieve the value from the database.
	handleAdd ($memberName, $arguments, $functionName)
	Overridden to fetch data before manipulation.
	handleRemove ($memberName, $arguments, $functionName)
	Overridden to fetch data before manipulation.
	handleGetUntranslated ($memberName, $arguments, $functionName)
	Overridden to fetch data.
	handleGetFromArray ($memberName, $arguments, $functionName)
	Overridden to fetch data.
	initLocalizedMember ($memberName)
	Makes sure a localized member contains a spunQ_Map.
Static Protected Member Functions
static	loadInjectedMember ($connection, spunQ_InjectedMember $injectedMember)
	Loads injected members for several objects.
Protected Attributes
	$limit = NULL
	The number of entries to select at most.
	$offset = NULL
	The number of entries to skip.
	$orders = array()
	The property by which the result set will be ordered.
	$type
	The type to fetch.
	$properties = array()
	The properties to select.
	$conditions = array()
	Conditions to this query.
	$returnType = self::RETURN_OBJECTS
	Definition of the return type.
	$id
	The unique id of this object.
	$remoteValues = array()
	Members that have been loaded from the database.
	$locallyModifiedMembers = array()

	$connection = NULL
	The connection that is persisting this object.
	$_type
	The actual type of this object.