CONTENIDO_4.9.0 beta1
Back to top  

Class ItemCollection Abstract class for database based item collections.

Base class with common features for database based items and item collections.

copyright four for business AG

 Methods

Constructor function for downwards compatibility

ItemCollection($sTable, $sPrimaryKey, $iLifetime) 

Parameters

$sTable

$sPrimaryKey

$iLifetime

Magic method to invoke inaccessible methods.

__call(string $name, array $arguments) : mixed

Currently it works as a fallback for the not supported method create() which creates a PHP Strict warning.

Parameters

$name

string

$arguments

array

Returns

mixed

Constructor Function

__construct(string $sTable, string $sPrimaryKey, int $iLifetime) : void

Parameters

$sTable

string

The table to use as information source

$sPrimaryKey

string

The primary key to use

$iLifetime

int

Exceptions

\cInvalidArgumentException If table name or primary key is not set

Adds a result field

addResultField(string $sField) 

Parameters

$sField

string

Inserts a new item entry by using a existing item entry.

copyItem(object $srcItem, array $fieldsToOverwrite) : object | \Item | null

Parameters

$srcItem

object

Source Item instance to copy

$fieldsToOverwrite

array

Assoziative list of fields to overwrite.

Exceptions

\cInvalidArgumentException If Item class doesn't match the defined _itemClass property or passed Item instance has no loaded recordset

Returns

object\Itemnull

Returns the amount of returned items

count() : int

Returns

intNumber of rows

Creates a new item in the table and loads it afterwards.

createNewItem(string | array $data) : \Item

Parameters

$data

stringarray

optional parameter for direct input of primary key value (string) or multiple column name - value pairs

Returns

\ItemThe newly created object

Deletes an item in the table.

delete(mixed $mId) : bool

Deletes also cached e entry and any existing properties.

Parameters

$mId

mixed

Id of entry to delete

Returns

bool

Deletes all found items in the table matching the passed field and it's value.

deleteBy(string $sField, mixed $mValue) : int

Deletes also cached e entries and any existing properties.

Parameters

$sField

string

The field name

$mValue

mixed

The value of the field

Returns

intNumber of deleted entries

Deletes all found items in the table matching the passed field and it's value.

deleteByMany($values) : bool

Deletes also cached e entries and any existing properties.

Parameters

$values

Returns

bool

Deletes all found items in the table matching the rules in the passed where clause.

deleteByWhereClause(string $sWhere) : int

Deletes also cached e entries and any existing properties.

Parameters

$sWhere

string

The where clause of the SQL statement

Returns

intNumber of deleted entries

Removes a previous set where clause (@see ItemCollection::setWhere).

deleteWhere(string $sField, mixed $mRestriction, string $sOperator) 

Parameters

$sField

string

$mRestriction

mixed

$sOperator

string

Removes a previous set groupable where clause (@see ItemCollection::setWhereGroup).

deleteWhereGroup(string $sGroup, string $sField, mixed $mRestriction, string $sOperator) 

Parameters

$sGroup

string

$sField

string

$mRestriction

mixed

$sOperator

string

Escape string for using in SQL-Statement.

escape(string $sString) : string
Inherited
inherited_from \cItemBaseAbstract::escape()

Parameters

$sString

string

The string to escape

Returns

stringEscaped string

Checks if a specific entry exists.

exists(mixed $mId) : bool

Parameters

$mId

mixed

The id to check for (could be numeric or string)

Returns

boolTrue if object exists, false if not

Fetches an array of fields from the database.

fetchArray(string $sKey, mixed $mFields) : array

Example: $i = $object->fetchArray('idartlang', array('idlang', 'name'));

could result in: $i[5] = array('idlang' => 5, 'name' => 'My Article');

Important: If you don't pass an array for fields, the function doesn't create an array.

Parameters

$sKey

string

Name of the field to use for the key

$mFields

mixed

String or array

Returns

arrayResulting array

Loads a single entry by it's id.

fetchById(string | int $id) : \Item

Parameters

$id

stringint

The primary key of the item to load.

Returns

\ItemThe loaded item

Fetches the resultset related to current loaded primary key as an object

fetchObject(\Item $sClassName) 

Parameters

$sClassName

\Item

fetchTable() 

fetchTable(array $aFields, array $aObjects) 

Parameters

$aFields

$aObjects

Selects all entries from the database.

flexSelect(string $sDistinct, string $sFrom, string $sWhere, string $sGroupBy, string $sOrderBy, string $sLimit) : bool

Objects are loaded using their primary key.

author HerrB

Parameters

$sDistinct

string

Specifies if distinct will be added to the SQL statement ($sDistinct !== '' -> DISTINCT)

$sFrom

string

Specifies the additional from clause (e.g. 'con_news_groups AS groups, con_news_groupmembers AS groupmembers').

$sWhere

string

Specifies the where clause.

$sGroupBy

string

Specifies the group by clause.

$sOrderBy

string

Specifies the order by clause.

$sLimit

string

Specifies the limit by clause.

Returns

boolTrue on success, otherwhise false

Returns all ids of recordsets in the table.

getAllIds() : array

Returns

arrayList of ids

Returns all specified fields of recordsets in the table matching the rules in the passed where clause.

getFieldsByWhereClause(array $aFields, string $sWhere) : array

Parameters

$aFields

array

List of fields to get

$sWhere

string

The where clause of the SQL statement

Returns

arrayList of entries with specified fields

Returns all ids of recordsets in the table matching the rules in the passed where clause.

getIdsByWhereClause(string $sWhere) : array

Parameters

$sWhere

string

The where clause of the SQL statement

Returns

arrayList of ids

Sets the query to use foreign tables in the resultset

link(string $sForeignClass) : void

Parameters

$sForeignClass

string

The class of foreign table to use

Exceptions

\cInvalidArgumentException if the given foreign class does not exist

Loads a single object from the database.

loadItem(mixed $mItem) : \Item

Parameters

$mItem

mixed

The primary key of the item to load or a recordset with itemdata (array) to inject to the item object.

Exceptions

\cException If item class is not set

Returns

\ItemThe newly created object

Advances to the next item in the database.

next() : \Item | bool

Returns

\ItemboolThe next object, or false if no more objects

Builds and runs the query

query() : bool

Exceptions

\cException if no item class has been set

Returns

bool

Returns an array of arrays

queryAndFetchStructured(array $aObjects) : array

Parameters

$aObjects

array

With the correct order of the objects

Returns

arrayResult

Registers a new callback.

register(string $event, mixed $callback, mixed $class) : void
InheritedStatic

Example: cGenericDb::register(cGenericDb::CREATE_SUCCESS, 'itemCreateHandler', 'cApiArticle'); cGenericDb::register(cGenericDb::CREATE_SUCCESS, array('cCallbackHandler', 'executeCreateHandle'), 'cApiArticle');

inherited_from \cGenericDb::register()
inherited_from \cItemBaseAbstract::register()

Parameters

$event

string

Callback event, must be a valid value of a cGenericDb event constant

$callback

mixed

Callback to register

$class

mixed

Class name for registering callback (can be string of array with names of the concrete Item classes)

Exceptions

\cInvalidArgumentException if event or class are not set or the callback is not callable

Removes existing result field

removeResultField(string $sField) 

Parameters

$sField

string

Resets the properties

resetQuery() 

Selects all entries from the database.

select(string $sWhere, string $sGroupBy, string $sOrderBy, string $sLimit) : bool

Objects are loaded using their primary key.

Parameters

$sWhere

string

Specifies the where clause.

$sGroupBy

string

Specifies the group by clause.

$sOrderBy

string

Specifies the order by clause.

$sLimit

string

Specifies the limit by clause.

Returns

boolTrue on success, otherwhise false

Sets the encoding.

setEncoding(string $sEncoding) 

Parameters

$sEncoding

string

Defines how groups are linked to each other

setGroupCondition(string $sGroup1, string $sGroup2, string $sCondition) 

Parameters

$sGroup1

string

$sGroup2

string

$sCondition

string

Defines how relations in one group are linked each together

setInnerGroupCondition(string $sGroup, string $sCondition) 

Parameters

$sGroup

string

$sCondition

string

Sets the limit for results

setLimit(int $iRowStart, int $iRowCount) 

Parameters

$iRowStart

int

$iRowCount

int

Sets the result order part of the query (e.

setOrder(string $order) 

g. "fieldname", "fieldname DESC", "fieldname DESC, field2name ASC")

Parameters

$order

string

Restricts a query with a where clause

setWhere(string $sField, mixed $mRestriction, string $sOperator) 

Parameters

$sField

string

$mRestriction

mixed

$sOperator

string

Restricts a query with a where clause, groupable

setWhereGroup(string $sGroup, string $sField, mixed $mRestriction, string $sOperator) 

Parameters

$sGroup

string

$sField

string

$mRestriction

mixed

$sOperator

string

Unregisters all callbacks for a specific event in a class.

unregister(string $event, mixed $class) : void
InheritedStatic

Example: cGenericDb::unregister(cGenericDb::CREATE_SUCCESS, 'cApiArticle');

inherited_from \cGenericDb::unregister()
inherited_from \cItemBaseAbstract::unregister()

Parameters

$event

string

Callback event, must be a valid value of a cGenericDb event constant

$class

mixed

Class name for unregistering callback (can be string of array with names of the concrete Item classes)

Exceptions

\cInvalidArgumentException if the event or the class are not set

Builds a where statement out of the setGroupWhere calls

_buildGroupWhereStatements() : array

Returns

arrayWith all where statements

Builds a where statement out of the setWhere calls

_buildWhereStatements() : array

Returns

arrayWith all where statements

Deletes an item in the table, deletes also existing cache entries and properties of the item.

_delete(mixed $mId) : bool

Parameters

$mId

mixed

Id of entry to delete

Returns

bool

Deletes all items in the table, deletes also existing cache entries and properties of the item.

_deleteMultiple(array $aIds) : int

Parameters

$aIds

array

Id of entries to delete

Returns

intNumber of affected records

Executes all callbacks for a specific event in a class.

_executeCallbacks(string $event, string $class, array $arguments) : void
Inherited
inherited_from \cGenericDb::_executeCallbacks()
inherited_from \cItemBaseAbstract::_executeCallbacks()

Parameters

$event

string

Callback event, must be a valid value of a cGenericDb event constant

$class

string

Class name for executing callback

$arguments

array

Arguments to pass to the callback function

Exceptions

\cInvalidArgumentException if the event or class is not set

Fetches all tables which will be joined later on.

_fetchJoinTables(\??? $ignoreRoot) : array

The returned array has the following format:

array(
    array(fields),
    array(tables),
    array(joins),
    array(wheres)
);

Notes: The table is the table name which needs to be added to the FROM clause The join statement which is inserted after the master table The where statement is combined with all other where statements The fields to select from

todo Reduce complexity of this function, to much code...

Parameters

$ignoreRoot

\???

Exceptions

\cException if no join partner could be found

Returns

arrayArray structure, see above

Returns reverse join partner.

_findReverseJoinPartner(string $sParentClass, string $sClassName) 

Parameters

$sParentClass

string

$sClassName

string

Returns properties instance, instantiates it if not done before.

_getPropertiesCollectionInstance() : \cApiPropertyCollection
Inherited
inherited_from \cItemBaseAbstract::_getPropertiesCollectionInstance()

Returns

\cApiPropertyCollection

Returns the second database instance, usable to run additional statements without losing current query results.

_getSecondDBInstance() : \cDb
Inherited
inherited_from \cItemBaseAbstract::_getSecondDBInstance()

Returns

\cDb

Initializes the driver to use with GenericDB.

_initializeDriver($bForceInit) 

Parameters

$bForceInit

boolean If true, forces the driver to initialize, even if it already exists.

_recursiveStructuredFetch() 

_recursiveStructuredFetch(array $aObjects, array $aResult) 

Parameters

$aObjects

$aResult

Resolves links (class names of joined partners)

_resolveLinks() : array

Returns

array

Method to set the accompanying item object.

_setItemClass(string $sClassName) : void

Parameters

$sClassName

string

Specifies the classname of item

Exceptions

\cInvalidArgumentException if the given class can not be instantiated

Defines the reverse links for this table.

_setJoinPartner(string $sForeignCollectionClass) : void

Important: The class specified by $sForeignCollectionClass needs to be a collection class and has to exist. Define all links in the constructor of your object.

Parameters

$sForeignCollectionClass

string

Specifies the foreign class to use

Exceptions

\cInvalidArgumentException if the given foreign class can not be instantiated

 Properties

 

$primaryKey : string
Inherited
inherited_from \cItemBaseAbstract::$$primaryKey
 

$virgin : bool
Inherited

If true, the object is virgin and no operations on it except load-Functions are allowed.

inherited_from \cItemBaseAbstract::$$virgin
 

Reverse join partners for this data object

$_JoinPartners : array
 

$_aOperators : array
 

$_bAllMode : bool

Reduces the number of queries send to the database.

 

$_className : string
Inherited
inherited_from \cItemBaseAbstract::$$_className
 

$_collectionCache : array
 

$_driver : \cGenericDbDriver
 

Encoding

$_encoding : string
 

Forward join partners for this data object

$_forwardJoinPartners : array
 

Group conditions

$_groupConditions : array
 

Inner group conditions

$_innerGroupConditions : array
 

Single item class

$_itemClass : string
 

Iterator object for the next() method

$_iteratorItem : object
 

$_oCache : \cItemCache
Inherited
inherited_from \cItemBaseAbstract::$$_oCache
 

Result fields for the query

$_resultFields : array
 

$_settings : array
Inherited
inherited_from \cItemBaseAbstract::$$_settings
 

Where restrictions for the query

$_whereRestriction : array
 

$cache : array
Inherited
inherited_from \cItemBaseAbstract::$$cache
 

$db : \cDb
Inherited
inherited_from \cItemBaseAbstract::$$db
 

$lasterror : string
Inherited
inherited_from \cItemBaseAbstract::$$lasterror
 

$lifetime : int
Inherited
inherited_from \cItemBaseAbstract::$$lifetime
 

$objects : string
 

$properties : \cApiPropertyCollection
Inherited
inherited_from \cItemBaseAbstract::$$properties
 

$secondDb : \cDb
Inherited
inherited_from \cItemBaseAbstract::$$secondDb
 

$table : string
Inherited
inherited_from \cItemBaseAbstract::$$table
 

$_callbacks : array
Inherited
inherited_from \cGenericDb::$$_callbacks
inherited_from \cItemBaseAbstract::$$_callbacks

 Constants

 

Callbacks are executed before a item is created.

CREATE_BEFORE 
Inherited

Expected parameters for callback: none

inherited_from \cGenericDb::CREATE_BEFORE
inherited_from \cItemBaseAbstract::CREATE_BEFORE
 

Callbacks are executed if item could not be created.

CREATE_FAILURE 
Inherited

Expected parameters for callback: none

inherited_from \cGenericDb::CREATE_FAILURE
inherited_from \cItemBaseAbstract::CREATE_FAILURE
 

Callbacks are executed if item could be created successfully.

CREATE_SUCCESS 
Inherited

Expected parameters for callback: ID of created item

inherited_from \cGenericDb::CREATE_SUCCESS
inherited_from \cItemBaseAbstract::CREATE_SUCCESS
 

Callbacks are executed before deleting an item.

DELETE_BEFORE 
Inherited

Expected parameters for callback: ID of them item to delete

inherited_from \cGenericDb::DELETE_BEFORE
inherited_from \cItemBaseAbstract::DELETE_BEFORE
 

Callbacks are executed if deletion of an item fails.

DELETE_FAILURE 
Inherited

Expected parameters for callback: ID of them item to delete

inherited_from \cGenericDb::DELETE_FAILURE
inherited_from \cItemBaseAbstract::DELETE_FAILURE
 

Callbacks are executed if item was deleted successfully.

DELETE_SUCCESS 
Inherited

Expected parameters for callback: ID of them item to delete

inherited_from \cGenericDb::DELETE_SUCCESS
inherited_from \cItemBaseAbstract::DELETE_SUCCESS
 

Callbacks are executed before store process is executed.

STORE_BEFORE 
Inherited

Expected parameters for callback: Item instance

inherited_from \cGenericDb::STORE_BEFORE
inherited_from \cItemBaseAbstract::STORE_BEFORE
 

Callbacks are executed if store process failed.

STORE_FAILURE 
Inherited

This is also likely to happen if query would not change anything in database! Expected parameters for callback: Item instance

inherited_from \cGenericDb::STORE_FAILURE
inherited_from \cItemBaseAbstract::STORE_FAILURE
 

Callbacks are executed if store process saved the values in the database.

STORE_SUCCESS 
Inherited

Expected parameters for callback: Item instance

inherited_from \cGenericDb::STORE_SUCCESS
inherited_from \cItemBaseAbstract::STORE_SUCCESS