Any entities the session manager retrieves from the data store are persisted in an identity map. When an entity is requested, the manager checks its identity map (a Xyster_Orm_Repository object) for the presence of the requested entity. If it's found, it's returned, otherwise the manager uses a data mapper to connect to the data store. Persisting entities in the identity map prevents unnecessary visits to the data store if the same entity is requested more than once.

<?php
$orm = Xyster_Orm::getInstance();
$entityClassName = 'Person';
$primaryKey = 1;
$entity = $orm->get($entityClassName, $primaryKey);   // retrieves from store
$entity = $orm->get($entityClassName, $primaryKey);   // retrieves from id map
$entity = $orm->get($entityClassName, 1234567);       // if not found, null

In addition to the get method, you can use the find method to search for entities based on value. The find method will always query the data store. (Tip: In the world of SQL databases, find queries work quickest on indexed columns.)

<?php
// the criteria array has keys as columns
$criteria = array('name' => 'Darth Vader');
// it can also be an actual Criterion object
$criteria = Xyster_Data_Expression::eq('name', 'Darth Vader');
$vader = $orm->find('Person', $criteria);

You can also get a collection of entities.

<?php
// gets all entities of a certain type; be careful w/ large numbers!
$people = $orm->getAll('Person');
// you can supply an array of primary keys
$people = $orm->getAll('Person', array(1, 2, 3, 4));

And you can find them.

<?php
// multiple values for a field will be used like Expression::in()
$criteria = array('name' => array('Luke Skywalker', 'Darth Vader'));
// and you can still use Criterion objects
$criteria = Xyster_Data_Expression::in('name', array('Luke Skywalker', 'Darth Vader'));
// you can specify a sort order just like Xyster_Data_Set::sortBy
$sorts = Xyster_Data_Sort::desc("name");
$people = $orm->findAll('Person', $criteria, $sorts);

At any time, you can refresh an existing entity with current data from the store.

<?php
$luke = $orm->get('Person',1);
$orm->refresh($luke);
		

Changes can be made to entities and committed back to the data store. Let's face it, that's really the whole reason to do this. A work unit session can be committed or destroyed.

<?php
$luke = $orm->get('Person', 1);
$luke->affiliation = 'Jedi Knights';
$orm->commit(); // the change to the entity will be flushed back to the data store
$luke->affiliation = 'Jedi';
$orm->destroy(); // abandons all changes, unloads all entities, clears any cache

You can store new entities very easily.

<?php
$leia = new Person();
$leia->name = 'Princess Leia Organa';
$leia->affiliation = 'Rebel';
$leia->alignment = 'good';
$leia->gender = 'F';
$leia->race = 'Human';
$orm->persist($leia);
echo $leia->personId; // prints null
$orm->commit();
echo $leia->personId; // prints new primary key

You can also delete entities very easily.

<?php
$vader = $orm->get('person',2);
$orm->remove($vader);
$orm->commit();

It's incredibly wise from a performance standpoint to take advantage of the secondary cache mechanism. Entities in the identity map the manager uses are only persisted for the lifetime of the object instance; just one request. If the secondary cache is defined, entities will be placed there and are persisted across many requests. This also allows sharing of the entities between user sessions.

<?php
$cache = Zend_Cache::factory('Core', 'Zend Platform');
$orm->setSecondaryCache($cache);

Entities are first tried to be located in the Xyster_Orm_Repository, then if not found, the Zend_Cache_Core object supplied to the setSecondaryCache method. Finally, if still not found, the entity is pulled out of the data store through the data mapper.