Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcPersistentSession

PersistentObject::ezcPersistentSession

Class ezcPersistentSession

ezcPersistentSession is the main runtime interface for manipulation of persistent objects.

Persistent objects can be stored calling save() resulting in an INSERT query. If the object is already persistent you can store it using update() which results in an UPDATE query. If you want to query persistent objects you can use the find methods.

Source for this file: /PersistentObject/src/persistent_session.php

Implements interfaces:

Version:   //autogen//

Properties

ezcDbHandler read $database
The database handler set in the constructor.
ezcPersistentDefinitionManager read $definitionManager
The persistent definition manager set in the constructor.

Method Summary

public ezcPersistentSession __construct( $db , $manager )
Constructs a new persistent session that works on the database $db.
public void addRelatedObject( $object , $relatedObject , [ $relationName = null] )
Create a relation between $object and $relatedObject.
public ezcQueryDelete createDeleteQuery( $class )
Returns a delete query for the given persistent object $class.
public ezcQuerySelect createFindQuery( $class )
Returns a select query for the given persistent object $class.
public ezcPersistentFindQuery createRelationFindQuery( $object , $relatedClass , [ $relationName = null] )
Returns the base query for retrieving related objects.
public ezcQuerySubSelect createSubQuery( $parentQuery , $class )
Returns a sub-select for the given $class to be used with $parentQuery.
public ezcQueryUpdate createUpdateQuery( $class )
Returns an update query for the given persistent object $class.
public void delete( $object )
Deletes the persistent object $object.
public void deleteFromQuery( $query )
Deletes persistent objects using the query $query.
public array(object($class)) find( $query , [ $class = null] )
Returns the result of the query $query as a list of objects.
public ezcPersistentFindIterator findIterator( $query , [ $class = null] )
Returns the result of $query for the $class as an iterator.
public array(string=>string) generateAliasMap( $def , [ $prefixTableName = true] )
Returns a hash map between property and column name for the given definition $def.
public array(int=>string) getColumnsFromDefinition( $def , [ $prefixTableName = true] )
Returns all the columns defined in the persistent object.
public array getObjectState( $object )
Returns the object state.
public object($relatedClass) getRelatedObject( $object , $relatedClass , [ $relationName = null] )
Returns the related object of a given $relatedClass for an $object.
public array(int=>object($relatedClass)) getRelatedObjects( $object , $relatedClass , [ $relationName = null] )
Returns the related objects of a given $relatedClass for an $object.
public bool isRelated( $sourceObject , $relatedObject , [ $relationName = null] , $sourceObj , $relatedObj )
Returns if $relatedObject is related to $sourceObject.
public object load( $class , $id )
Returns the persistent object of class $class with id $id.
public object|null loadIfExists( $class , $id )
Returns the persistent object of class $class with id $id.
public void loadIntoObject( $object , $id )
Loads the persistent object with the id $id into the object $object.
public PDOStatement performQuery( $q , [ $transaction = false] )
Performs the given query.
public void refresh( $object )
Syncronizes the contents of $object with those in the database.
public void removeRelatedObject( $object , $relatedObject , [ $relationName = null] )
Removes the relation between $object and $relatedObject.
public void save( $object )
Saves the new persistent object $object to the database using an INSERT INTO query.
public void saveOrUpdate( $object )
Saves or updates the persistent object $object to the database.
public void update( $object )
Saves the new persistent object $object to the database using an UPDATE query.
public void updateFromQuery( $query )
Updates persistent objects using the query $query.

Methods

__construct

ezcPersistentSession __construct( $db , ezcPersistentDefinitionManager $manager )

Constructs a new persistent session that works on the database $db.

The $manager provides valid persistent object definitions to the session. The $db will be used to perform all database operations.

Parameters:
Name Type Description
$db ezcDbHandler
$manager ezcPersistentDefinitionManager

addRelatedObject

void addRelatedObject( object $object , object $relatedObject , [string $relationName = null] )

Create a relation between $object and $relatedObject.

This method is used to create a relation between the given source $object and the desired $relatedObject. The related object is not stored in the database automatically, only the desired properties are set. An exception is {@ezcPersistentManyToManyRelation}s, where the relation record is stored automatically and there is no need to store $relatedObject explicitly after establishing the relation.

If there are multiple relations defined between the class of $object and $relatedObject (via ezcPersistentRelationCollection), the $relationName parameter becomes mandatory to determine, which exact relation should be used.

Parameters:
Name Type Description
$object object
$relatedObject object
$relationName string
Exceptions:
Type Description
ezcPersistentRelationNotFoundException if the deisred relation is not defined.
ezcPersistentRelationOperationNotSupportedException if a relation to create is marked as "reverse" ezcPersistentRelation->reverse.
Implementation of:
Method Description
ezcPersistentSessionFoundation::addRelatedObject() Create a relation between $object and $relatedObject.

createDeleteQuery

ezcQueryDelete createDeleteQuery( string $class )

Returns a delete query for the given persistent object $class.

The query is initialized to delete from the correct table and it is only neccessary to set the where clause.

Example:

  1.  $q = $session->createDeleteQuery( 'Person' );
  2.  $q->where( $q->expr->gt( 'age', $q->bindValue( 15 ) ) );
  3.  $session->deleteFromQuery( $q );
Parameters:
Name Type Description
$class string
Exceptions:
Type Description
ezcPersistentObjectException if there is no such persistent class.
Implementation of:
Method Description
ezcPersistentSessionFoundation::createDeleteQuery() Returns a delete query for the given persistent object $class.

createFindQuery

ezcQuerySelect createFindQuery( string $class )

Returns a select query for the given persistent object $class.

The query is initialized to fetch all columns from the correct table and has correct alias mappings between columns and property names of the persistent $class.

Example:

  1.  $q = $session->createFindQuery( 'Person' );
  2.  $allPersons = $session->find( $q, 'Person' );
Parameters:
Name Type Description
$class string
Exceptions:
Type Description
ezcPersistentObjectException if there is no such persistent class.
Implementation of:
Method Description
ezcPersistentSessionFoundation::createFindQuery() Returns a select query for the given persistent object $class.

createRelationFindQuery

ezcPersistentFindQuery createRelationFindQuery( object $object , string $relatedClass , [string $relationName = null] )

Returns the base query for retrieving related objects.

See getRelatedObject() and getRelatedObjects(). Can be modified by additional where conditions and simply be used with find() and the related class name, to retrieve a sub-set of related objects.

If multiple relations are defined for the $relatedClass (using ezcPersistentRelationCollection), the parameter $relationName becomes mandatory to determine which relation definition to use. For normal relations, this parameter is silently ignored.

Parameters:
Name Type Description
$object object
$relatedClass string
$relationName string
Exceptions:
Type Description
ezcPersistentRelationNotFoundException if the given $object does not have a relation to $relatedClass.
Implementation of:
Method Description
ezcPersistentSessionFoundation::createRelationFindQuery() Returns the base query for retrieving related objects.

createSubQuery

ezcQuerySubSelect createSubQuery( ezcPersistentFindQuery $parentQuery , string $class )

Returns a sub-select for the given $class to be used with $parentQuery.

This method creates an ezcPersistentFindQuery as a ezcQuerySubSelect for the given $class. The returned query has already set aliases for the properties of $class, but (in contrast to the query returned by createFindQuery()) does not have the selection of all properties set. You need to do

  1.  <?php
  2.  $subSelect = $session->subSelect( $existingSelectQuery, 'MyClass' );
  3.  $subSelect->select( 'myField' );
  4.  ?>

manually to select the fields you desire.

Parameters:
Name Type Description
$parentQuery ezcPersistentFindQuery
$class string

createUpdateQuery

ezcQueryUpdate createUpdateQuery( string $class )

Returns an update query for the given persistent object $class.

The query is initialized to update the correct table and it is only neccessary to set the correct values.

Parameters:
Name Type Description
$class string
Exceptions:
Type Description
ezcPersistentDefinitionNotFoundException if there is no such persistent class.
Implementation of:
Method Description
ezcPersistentSessionFoundation::createUpdateQuery() Returns an update query for the given persistent object $class.

delete

void delete( object $object )

Deletes the persistent object $object.

This method will perform a DELETE query based on the identifier of the persistent object $object. After delete() the ID property of $object will be reset to null. It is possible to save() $object afterwards. $object will then be stored with a new ID.

If you defined relations for the given object, these will be checked to be defined as cascading. If cascading is configured, the related objects with this relation will be deleted, too.

Relations that support cascading are:

  • ezcPersistenOneToManyRelation
  • ezcPersistenOneToOne
Parameters:
Name Type Description
$object object The persistent object to delete.
Exceptions:
Type Description
ezcPersistentDefinitionNotFoundxception if $the object is not recognized as a persistent object.
ezcPersistentObjectNotPersistentException if the object is not persistent already.
ezcPersistentQueryException if the object could not be deleted.
Implementation of:
Method Description
ezcPersistentSessionFoundation::delete() Deletes the persistent object $object.

deleteFromQuery

void deleteFromQuery( $query )

Deletes persistent objects using the query $query.

The $query should be created using createDeleteQuery().

Currently this method only executes the provided query. Future releases PersistentSession may introduce caching of persistent objects. When caching is introduced it will be required to use this method to run cusom delete queries. To avoid being incompatible with future releases it is advisable to always use this method when running custom delete queries on persistent objects.

Parameters:
Name Type Description
$query ezcQueryDelete
Exceptions:
Type Description
ezcPersistentQueryException if the delete query failed.
Implementation of:
Method Description
ezcPersistentSessionFoundation::deleteFromQuery() Deletes persistent objects using the query $query.

find

array(object($class)) find( ezcPersistentFindQuery|ezcQuerySelect $query , [string $class = null] )

Returns the result of the query $query as a list of objects.

Returns the persistent objects found for $class using the submitted $query. $query should be created using createFindQuery() to ensure correct alias mappings and can be manipulated as needed.

Example:

  1.  $q = $session->createFindQuery( 'Person' );
  2.  $allPersons = $session->find( $q, 'Person' );

If you are retrieving large result set, consider using findIterator() instead.

Example:

  1.  $q = $session->createFindQuery( 'Person' );
  2.  $objects = $session->findIterator( $q, 'Person' );
  3.  
  4.  foreach( $objects as $object )
  5.  {
  6.      // ...
  7.  }
Parameters:
Name Type Description
$query ezcPersistentFindQuery|ezcQuerySelect
$class string
Exceptions:
Type Description
ezcPersistentDefinitionNotFoundException if there is no such persistent class.
ezcPersistentQueryException if the find query failed.
ezcBaseValueException if $query parameter is not an instance of ezcPersistentFindQuery or ezcQuerySelect. Or if $class is missing if you use ezcQuerySelect.
Implementation of:
Method Description
ezcPersistentSessionFoundation::find() Returns the result of the query $query as a list of objects.

findIterator

ezcPersistentFindIterator findIterator( ezcPersistentFindQuery|ezcQuerySelect $query , [string $class = null] )

Returns the result of $query for the $class as an iterator.

This method is similar to find() but returns an ezcPersistentFindIterator instead of an array of objects. This is useful if you are going to loop over the objects and just need them one at the time. Because you only instantiate one object it is faster than find(). In addition, only 1 record is retrieved from the database in each iteration, which may reduce the data transfered between the database and PHP, if you iterate only through a small subset of the affected records.

Note that if you do not loop over the complete result set you must call ezcPersistentFindIterator::flush() before issuing another query.

Parameters:
Name Type Description
$query ezcPersistentFindQuery|ezcQuerySelect
$class string
Exceptions:
Type Description
ezcPersistentDefinitionNotFoundException if there is no such persistent class.
ezcPersistentQueryException if the find query failed.
ezcBaseValueException if $query parameter is not an instance of ezcPersistentFindQuery or ezcQuerySelect. Or if $class is missing if you use ezcQuerySelect.
Implementation of:
Method Description
ezcPersistentSessionFoundation::findIterator() Returns the result of $query for the $class as an iterator.

generateAliasMap

array(string=>string) generateAliasMap( ezcPersistentObjectDefinition $def , [bool $prefixTableName = true] )

Returns a hash map between property and column name for the given definition $def.

The alias map can be used with the query classes. If $prefixTableName is set to false, only the column names are used as alias targets.

Parameters:
Name Type Description
$def ezcPersistentObjectDefinition Definition.
$prefixTableName bool
Implementation of:
Method Description
ezcPersistentSessionFoundation::generateAliasMap() Returns a hash map between property and column name for the given definition $def.

getColumnsFromDefinition

array(int=>string) getColumnsFromDefinition( ezcPersistentObjectDefinition $def , [bool $prefixTableName = true] )

Returns all the columns defined in the persistent object.

If $prefixTableName is set to false, raw column names will be used, without prefixed table name.

Parameters:
Name Type Description
$def ezcPersistentObjectDefinition Defintion.
$prefixTableName bool
Implementation of:
Method Description
ezcPersistentSessionFoundation::getColumnsFromDefinition() Returns all the columns defined in the persistent object.

getObjectState

array getObjectState( object $object )

Returns the object state.

This method wraps around $object->getState() to add optional sanity checks to this call, like a correct return type of getState() and correct keys and values in the returned array.

Parameters:
Name Type Description
$object object

getRelatedObject

object($relatedClass) getRelatedObject( object $object , string $relatedClass , [string $relationName = null] )

Returns the related object of a given $relatedClass for an $object.

This method returns the related object of type $relatedClass for the object $object. This method (in contrast to getRelatedObjects()) always returns a single result object, no matter if more related objects could be found (e.g. ezcPersistentOneToManyRelation). If no related object is found, an exception is thrown, while getRelatedObjects() just returns an empty array in this case.

Example:

  1.  $person = $session->load( "Person", 1 );
  2.  $relatedAddress = $session->getRelatedObject( $person, "Address" );
  3.  echo "Address of this person: " . $relatedAddress->__toString();

Relations that should preferably be used with this method are:

For other relation types getRelatedObjects() is recommended.

If multiple relations are defined for the $relatedClass (using ezcPersistentRelationCollection), the parameter $relationName becomes mandatory to determine which relation definition to use. For normal relations, this parameter is silently ignored.

Parameters:
Name Type Description
$object object
$relatedClass string
$relationName string
Exceptions:
Type Description
ezcPersistentRelationNotFoundException if the given $object does not have a relation to $relatedClass.
Implementation of:
Method Description
ezcPersistentSessionFoundation::getRelatedObject() Returns the related object of a given $relatedClass for an $object.

getRelatedObjects

array(int=>object($relatedClass)) getRelatedObjects( object $object , string $relatedClass , [string $relationName = null] )

Returns the related objects of a given $relatedClass for an $object.

This method returns the related objects of type $relatedClass for the given $object. This method (in contrast to getRelatedObject()) always returns an array of found objects, no matter if only 1 object was found (e.g. ezcPersistentManyToOneRelation), none or several (ezcPersistentManyToManyRelation).

Example:

  1.  $person = $session->load( "Person", 1 );
  2.  $relatedAddresses = $session->getRelatedObjects( $person, "Address" );
  3.  echo "Number of addresses found: " . count( $relatedAddresses );

Relations that should preferably be used with this method are:

For other relation types getRelatedObject() is recommended.

If multiple relations are defined for the $relatedClass (using ezcPersistentRelationCollection), the parameter $relationName becomes mandatory to determine which relation definition to use. For normal relations, this parameter is silently ignored.

Parameters:
Name Type Description
$object object
$relatedClass string
$relationName string
Exceptions:
Type Description
ezcPersistentRelationNotFoundException if the given $object does not have a relation to $relatedClass.
Implementation of:
Method Description
ezcPersistentSessionFoundation::getRelatedObjects() Returns the related objects of a given $relatedClass for an $object.

isRelated

bool isRelated( $sourceObject , $relatedObject , [string $relationName = null] , ezcPersistentObject $sourceObj , ezcPersistentObject $relatedObj )

Returns if $relatedObject is related to $sourceObject.

Checks the relation conditions between $sourceObject and $relatedObject and returns true, if $relatedObject is related to $sourceObject, otherwise false. In case multiple relations are defined between the classes of $sourceObject and $relatedObject, the $relationName parameter becomes mandatory. If it is not provided in this case, an ezcPersistentUndeterministicRelationException is thrown.

Note that checking relations of type ezcPersistentManyToManyRelation will issue a database query. Other relations will not perform this.

Parameters:
Name Type Description
$sourceObj ezcPersistentObject
$relatedObj ezcPersistentObject
$relationName string
$sourceObject
$relatedObject

load

object load( string $class , int $id )

Returns the persistent object of class $class with id $id.

Parameters:
Name Type Description
$class string
$id int
Exceptions:
Type Description
ezcPersistentObjectException if there is no such persistent class.
ezcPersistentObjectException if the object is not available.
Implementation of:
Method Description
ezcPersistentSessionFoundation::load() Returns the persistent object of class $class with id $id.

loadIfExists

object|null loadIfExists( string $class , int $id )

Returns the persistent object of class $class with id $id.

This method is equivalent to load() except that it returns null instead of throwing an exception if the object does not exist.

Parameters:
Name Type Description
$class string
$id int
Implementation of:
Method Description
ezcPersistentSessionFoundation::loadIfExists() Returns the persistent object of class $class with id $id.

loadIntoObject

void loadIntoObject( object $object , int $id )

Loads the persistent object with the id $id into the object $object.

The class of the persistent object to load is determined by the class of $object.

Parameters:
Name Type Description
$object object
$id int
Exceptions:
Type Description
ezcPersistentObjectException if the object is not available.
ezcPersistentDefinitionNotFoundException if $object is not of a valid persistent object type.
ezcPersistentQueryException if the find query failed.
Implementation of:
Method Description
ezcPersistentSessionFoundation::loadIntoObject() Loads the persistent object with the id $id into the object $object.

performQuery

PDOStatement performQuery( $q , [bool $transaction = false] )

Performs the given query.

Performs the $query, checks for errors and throws an exception in case. Returns the generated statement object on success. If the $transaction parameter is set to true, the query is excuted transaction save.

Parameters:
Name Type Description
$q ezcQuery
$transaction bool

refresh

void refresh( object $object )

Syncronizes the contents of $object with those in the database.

Note that calling this method is equavalent with calling loadIntoObject() on $object with the id of $object. Any changes made to $object prior to calling refresh() will be discarded.

Parameters:
Name Type Description
$object object
Exceptions:
Type Description
ezcPersistentObjectException if $object is not of a valid persistent object type.
ezcPersistentObjectException if $object is not persistent already.
ezcPersistentObjectException if the select query failed.
Implementation of:
Method Description
ezcPersistentSessionFoundation::refresh() Syncronizes the contents of $object with those in the database.

removeRelatedObject

void removeRelatedObject( object $object , object $relatedObject , [string $relationName = null] )

Removes the relation between $object and $relatedObject.

This method is used to delete an existing relation between 2 objects. Like addRelatedObject() this method does not store the related object after removing its relation properties (unset), except for ezcPersistentManyToManyRelation()s, for which the relation record is deleted from the database.

If between the classes of $object and $relatedObject multiple relations are defined using a ezcPersistentRelationCollection, the $relationName parameter becomes necessary. It defines which exact relation to affect here.

Parameters:
Name Type Description
$object object Source object of the relation.
$relatedObject object Related object.
$relationName string
Exceptions:
Type Description
ezcPersistentRelationNotFoundException if the deisred relation is not defined.
ezcPersistentRelationOperationNotSupportedException if a relation to create is marked as "reverse".
Implementation of:
Method Description
ezcPersistentSessionFoundation::removeRelatedObject() Removes the relation between $object and $relatedObject.

save

void save( object $object )

Saves the new persistent object $object to the database using an INSERT INTO query.

The correct ID is set to $object.

Parameters:
Name Type Description
$object object
Exceptions:
Type Description
ezcPersistentObjectException if $object is not of a valid persistent object type.
ezcPersistentObjectException if the insert query failed.
ezcPersistentObjectException if $object is already stored to the database.
ezcPersistentObjectException if it was not possible to generate a unique identifier for the new object.
Implementation of:
Method Description
ezcPersistentSessionFoundation::save() Saves the new persistent object $object to the database using an INSERT INTO query.

saveOrUpdate

void saveOrUpdate( object $object )

Saves or updates the persistent object $object to the database.

If the object is a new object an INSERT INTO query will be executed. If the object is persistent already it will be updated with an UPDATE query.

Parameters:
Name Type Description
$object object
Exceptions:
Type Description
ezcPersistentDefinitionNotFoundException if the definition of the persistent object could not be loaded.
ezcPersistentObjectException if the insert or update query failed.
ezcPersistentObjectException if $object is not of a valid persistent object type.
ezcPersistentObjectException if any of the definition requirements are not met.
Implementation of:
Method Description
ezcPersistentSessionFoundation::saveOrUpdate() Saves or updates the persistent object $object to the database.

update

void update( object $object )

Saves the new persistent object $object to the database using an UPDATE query.

Parameters:
Name Type Description
$object object
Exceptions:
Type Description
ezcPersistentDefinitionNotFoundException if $object is not of a valid persistent object type.
ezcPersistentObjectNotPersistentException if $object is not stored in the database already.
ezcPersistentQueryException
Implementation of:
Method Description
ezcPersistentSessionFoundation::update() Saves the new persistent object $object to the database using an UPDATE query.

updateFromQuery

void updateFromQuery( $query )

Updates persistent objects using the query $query.

The $query should be created using createUpdateQuery().

Currently this method only executes the provided query. Future releases PersistentSession may introduce caching of persistent objects. When caching is introduced it will be required to use this method to run cusom delete queries. To avoid being incompatible with future releases it is advisable to always use this method when running custom delete queries on persistent objects.

Parameters:
Name Type Description
$query ezcQueryUpdate
Exceptions:
Type Description
ezcPersistentQueryException if the update query failed.
Implementation of:
Method Description
ezcPersistentSessionFoundation::updateFromQuery() Updates persistent objects using the query $query.
Documentation generated by phpDocumentor 1.4.3