eZ Components 2007.1.1

Getting Started

Components

Archive (1.2.3)
Authentication (1.0)
AuthenticationDatabaseTiein (1.0)
Base (1.3.1)
Cache (1.2)
Configuration (1.2)
ConsoleTools (1.3)
Database (1.3)
DatabaseSchema (1.2)
Debug (1.1)
EventLog (1.1)
EventLogDatabaseTiein (1.0.2)
Execution (1.0.4)
File (1.1.1)
Graph (1.1)
GraphDatabaseTiein (1.0)
ImageAnalysis (1.1.2)
ImageConversion (1.3)
Mail (1.3.1)
PersistentObject (1.3)
PersistentObjectDatabaseSchemaTiein (1.2)
PhpGenerator (1.0.4)
SignalSlot (1.1)
SystemInformation (1.0.5)
Template (1.2)
Translation (1.1.4)
TranslationCacheTiein (1.1.2)
Url (1.1)
UserInput (1.1.2)
Workflow (1.0.1)
WorkflowDatabaseTiein (1.0)
WorkflowEventLogTiein (1.0)

PersistentObject: ezcPersistentSession

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcPersistentSession

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

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.

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 )` 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 ezcDbSelectQuery	`createRelationFindQuery( $object, $relatedClass )` Returns the base query for retrieving related objects.
public ezcQueryUpdate	`createUpdateQuery( $class )` Returns an update query for the given persistent object $class.
public void	`delete( $pObject )` Deletes the persistent object $pObject.
public void	`deleteFromQuery( $query )` Deletes persistent objects using the query $query.
public array(object)	`find( $query, $class )` Returns the result of the query $query as a list of objects.
public Iterator	`findIterator( $query, $class )` Returns the result of the query $query for the class $class as an object iterator.
public array(string=>string)	`generateAliasMap( $def )` Returns a hash map between property and column name for the given definition $def.
public array(int=>string)	`getColumnsFromDefinition( $def )` Returns all the columns defined in the persistent object.
public object	`getRelatedObject( $object, $relatedClass )` Returns the related object of a given class for an object.
public array(int=>object)	`getRelatedObjects( $object, $relatedClass )` Returns the related objects of a given class for an object.
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( $pObject, $id )` Loads the persistent object with the id $id into the object $pObject.
public void	`refresh( $pObject )` Syncronizes the contents of $pObject with those in the database.
public void	`removeRelatedObject( $object, $relatedObject )` Removes the relation between $object and $relatedObject.
public void	`save( $pObject )` Saves the new persistent object $pObject to the database using an INSERT INTO query.
public void	`saveOrUpdate( $pObject )` Saves or update the persistent object $pObject to the database.
public void	`update( $pObject )` Saves the new persistent object $pObject 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.

Parameters

Name	Type	Description
`$db`	ezcDbHandler
`$manager`	ezcPersistentDefinitionManager

addRelatedObject

void addRelatedObject( object $object, object $relatedObject )

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.

Parameters

Name	Type	Description
`$object`	object	The object to create a relation from.
`$relatedObject`	object	The object to create a relation to.

Throws

Class	Description
`ezcPersistentRelationOperationNotSupportedException`	if a relation to create is marked as "reverse".
`ezcPersistentRelationNotFoundException`	if the deisred relation is not defined.

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();
2.  $q->where( $q->expr->gt( 'age', $q->bindValue( 15 ) ) );
3.  $session->deleteFromQuery( $q );

Parameters

Name	Type	Description
`$class`	string

Throws

Class	Description
`ezcPersistentObjectException`	if there is no such persistent 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.

Example:

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

Parameters

Name	Type	Description
`$class`	string

Throws

Class	Description
`ezcPersistentObjectException`	if there is no such persistent class.

createRelationFindQuery

ezcDbSelectQuery createRelationFindQuery( object $object, string $relatedClass )

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.

Parameters

Name	Type	Description
`$object`	object	Object to find related objects for.
`$relatedClass`	string	Class of the related objects to find.

Throws

Class	Description
`ezcPersistentRelationNotFoundException`	if the given $object does not have a relation to $relatedClass.

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

Throws

Class	Description
`ezcPersistentDefinitionNotFoundException`	if there is no such persistent class.

delete

void delete( object $pObject )

Deletes the persistent object $pObject.

This method will perform a DELETE query based on the identifier of the persistent object. After delete() the identifier in $pObject will be reset to null. It is possible to save() $pObject afterwords. The 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
`$pObject`	object	The persistent object to delete.

Throws

Class	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.

deleteFromQuery

void deleteFromQuery( $query )

Deletes persistent objects using the query $query.

The $query should be created using getDeleteQuery().

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

Throws

Class	Description
`ezcPersistentQueryException`	if the delete query failed.

find

array(object) find( $query, string $class )

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

Example:

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

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

Example:

Parameters

Name	Type	Description
`$query`	ezcQuerySelect
`$class`	string

Throws

Class	Description
`ezcPersistentDefinitionNotFoundException`	if there is no such persistent class.
`ezcPersistentQueryException`	if the find query failed

findIterator

Iterator findIterator( $query, string $class )

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

This method is similar to find() but returns an iterator instead of a list 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 is is faster than find().

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

Parameters

Name	Type	Description
`$query`	ezcQuerySelect
`$class`	string

Throws

Class	Description
`ezcPersistentDefinitionNotFoundException`	if there is no such persistent class.
`ezcPersistentQueryException`	if the find query failed

generateAliasMap

array(string=>string) generateAliasMap( ezcPersistentObjectDefinition $def )

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

The alias map can be used with the query classes.

Parameters

Name	Type	Description
`$def`	ezcPersistentObjectDefinition	Definition.

getColumnsFromDefinition

array(int=>string) getColumnsFromDefinition( ezcPersistentObjectDefinition $def )

Returns all the columns defined in the persistent object.

Parameters

Name	Type	Description
`$def`	ezcPersistentObjectDefinition	Defintion.

getRelatedObject

object getRelatedObject( object $object, string $relatedClass )

Returns the related object of a given class for an object.

This method returns the related object of type $relatedClass for the object $object. This method (in contrast to getRelatedObjects()) always a single result object, no matter if more objects could be found (e.g. ezcPersistentOneToManyRelation).

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:

{ezcPersistentManyToOneRelation}
{ezcPersistentOneToOneRelation}

Parameters

Name	Type	Description
`$object`	object	The object to fetch related objects for.
`$relatedClass`	string	The class of the related objects to fetch.

Throws

Class	Description
`ezcPersistentRelationNotFoundException`	if the given $object does not have a relation to $relatedClass.

getRelatedObjects

array(int=>object) getRelatedObjects( mixed $object, mixed $relatedClass )

Returns the related objects of a given class for an object.

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

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:

Parameters

Name	Type	Description
`$object`	mixed	The object to fetch related objects for.
`$relatedClass`	mixed	The class of the related objects to fetch.

Throws

Class	Description
`ezcPersistentRelationNotFoundException`	if the given $object does not have a relation to $relatedClass.

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

Throws

Class	Description
`ezcPersistentObjectException`	if the object is not available.
`ezcPersistentObjectException`	if there is no such persistent class.

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

loadIntoObject

void loadIntoObject( object $pObject, int $id )

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

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

Parameters

Name	Type	Description
`$pObject`	object
`$id`	int

Throws

Class	Description
`ezcPersistentObjectException`	if the object is not available.
`ezcPersistentDefinitionNotFoundException`	if $pObject is not of a valid persistent object type.
`ezcPersistentQueryException`	if the find query failed

refresh

void refresh( object $pObject )

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

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

Parameters

Name	Type	Description
`$pObject`	object

Throws

Class	Description
`ezcPersistentObjectException`	if $pObject is not of a valid persistent object type.
`ezcPersistentObjectException`	if $pObject is not persistent already
`ezcPersistentObjectException`	if the select query failed.

removeRelatedObject

void removeRelatedObject( object $object, object $relatedObject )

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 ezcPersistentManyToManyRelations, for which the relation record is deleted from the database.

Parameters

Name	Type	Description
`$object`	object	Source object of the relation.
`$relatedObject`	object	Related object.

Throws

Class	Description
`ezcPersistentRelationOperationNotSupportedException`	if a relation to create is marked as "reverse".
`ezcPersistentRelationNotFoundException`	if the deisred relation is not defined.

save

void save( object $pObject )

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

The correct ID is set to $pObject.

Parameters

Name	Type	Description
`$pObject`	object

Throws

Class	Description
`ezcPersistentObjectException`	if $pObject is not of a valid persistent object type.
`ezcPersistentObjectException`	if $pObject is already stored to the database.
`ezcPersistentObjectException`	if it was not possible to generate a unique identifier for the new object
`ezcPersistentObjectException`	if the insert query failed.

saveOrUpdate

void saveOrUpdate( object $pObject )

Saves or update the persistent object $pObject 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
`$pObject`	object

Throws

Class	Description
`ezcPersistentDefinitionNotFoundException`	if the definition of the persistent object could not be loaded
`ezcPersistentObjectException`	if $pObject is not of a valid persistent object type.
`ezcPersistentObjectException`	if any of the definition requirements are not met.
`ezcPersistentObjectException`	if the insert or update query failed.

update

void update( object $pObject )

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

Parameters

Name	Type	Description
`$pObject`	object

Throws

Class	Description
`ezcPersistentDefinitionNotFoundException`	if $pObject is not of a valid persistent object type.
`ezcPersistentObjectNotPersistentException`	if $pObject is not stored in the database already.
`ezcPersistentQueryException`

updateFromQuery

void updateFromQuery( $query )

Updates persistent objects using the query $query.

The $query should be created using getUpdateQuery().

Parameters

Name	Type	Description
`$query`	ezcQueryUpdate

Throws

Class	Description
`ezcPersistentQueryException`	if the update query failed.

Last updated: Wed, 28 Nov 2007

eZ Components

User menu

Path

eZ Components 2007.1.1

Getting Started

Components

PersistentObject: ezcPersistentSession

Class: ezcPersistentSession

Properties

Method Summary

Methods

__construct

Parameters

addRelatedObject

Parameters

Throws

createDeleteQuery

Parameters

Throws

createFindQuery

Parameters

Throws

createRelationFindQuery

Parameters

Throws

createUpdateQuery

Parameters

Throws

delete

Parameters

Throws

deleteFromQuery

Parameters

Throws

find

Parameters

Throws

findIterator

Parameters

Throws

generateAliasMap

Parameters

getColumnsFromDefinition

Parameters

getRelatedObject

Parameters

Throws

getRelatedObjects

Parameters

Throws

load

Parameters

Throws

loadIfExists

Parameters

loadIntoObject

Parameters

Throws

refresh

Parameters

Throws

removeRelatedObject

Parameters

Throws

save

Parameters

Throws

saveOrUpdate

Parameters

Throws

update

Parameters

Throws

updateFromQuery

Parameters

Throws