Apache Zeta Components - high quality PHP components

This interface defines the public methods of ezcPersistentSession and decorators for this class. The interface needs to be implemented by any class that can be used like ezcPersistentSession, especially, if this class shall be used with ezcPersistentSessionInstance.

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.

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 );

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' );

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.

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

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

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.

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

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.

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.

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

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:

• ezcPersistentManyToOneRelation
• ezcPersistentOneToOneRelation

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.

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:

• ezcPersistentOneToManyRelation
• ezcPersistentManyToManyRelation

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.

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

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

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.

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.

The correct ID is set to $object.

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.

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.