The persistent class

We want to make a simple class, representing a person, persistent using persistent object. It is a simple class with only a few members:

1. <?php
2. class Person
3. {
4. private id = null;
5. public name = null;
6. public age = null;
8. public function getState()
9. {
10. $result = array();
11. $result['id'] = $this->id;
12. $result['name'] = $this->name;
13. $result['age'] = $this->age;
14. return $result;
15. }
17. public function setState( array $properties )
18. {
19. foreach( $state as $key => $value )
20. {
21. $this->$key = $value;
22. }
23. }
24. }
25. ?>

The id member will map to the required persistent identifier. It has to default to null. This is not required for any of the other mapped members. The id field is a required unique identifier for this persistent object. It is generated by the identifier generator and usually maps to an auto increment column in the database. For simplicity we have made the name and age members of the Person class public. However, this is not required and in a real application you can use any access method you like e.g access methods or properties or even having the data completely private.

All persistent objects must implement the getState() and setState() methods. They are used to retrieve the state of the object when saving it and to set it when loading it. The getState() method should always return the complete state of the object while the setState() method should be prepared to only set one member at the time.

The persistence mapping

We are going to map the Person class onto the following SQL table:

CREATE TABLE persons
(
  id integer unsigned not null auto_increment,
  full_name varchar(255),
  age integer,
  PRIMARY KEY (id)
) TYPE=InnoDB;

The fields map one to one to the members of the Person class. Using the InnoDB type is not required. We strongly recommend it however, since it supports transactions. The id column is of the type auto_increment. This is required for the id generator that we will use. Other id generators may have other requirements to work as expected.

In order for Persistent Object to be able to store objects of the Person class into the persons table we need to tell it how the columns are mapped to class members. We will use the ezcPersistentCodeManager to fetch the definitions when required. ezcPersistentCodeManager requires us to define the mapping using the ezcPersistentObjectDefinition, ezcPersistentObjectIdProperty and ezcPersistentObjectProperty classes:

1. <?php
2. $def = new ezcPersistentObjectDefinition();
3. $def->table = "persons";
4. $def->class = "Person";
6. $def->idProperty = new ezcPersistentObjectIdProperty;
7. $def->idProperty->columnName = 'id';
8. $def->idProperty->propertyName = 'id';
9. $def->idProperty->generator = new ezcPersistentGeneratorDefinition( 'ezcPersistentSequenceGenerator' );
11. $def->properties['name'] = new ezcPersistentObjectProperty;
12. $def->properties['name']->columnName = 'full_name';
13. $def->properties['name']->propertyName = 'name';
14. $def->properties['name']->propertyType = ezcPersistentObjectProperty::PHP_TYPE_STRING;
16. $def->properties['age'] = new ezcPersistentObjectProperty;
17. $def->properties['age']->columnName = 'age';
18. $def->properties['age']->propertyName = 'age';
19. $def->properties['age']->propertyType = ezcPersistentObjectProperty::PHP_TYPE_INT;
21. return $def;
22. ?>

The first block of code creates the definition object and sets the database table and the name of the class to map. The second block defines the mapping of the identifier member and the algorithm that should be used to create identifiers for new objects. We will use the ezcPersistentSequenceGenerator which simply retrieves the new identifier generated by auto_increment.

The next two code blocks define the mapping between the database columns and the class members. It is possible to use the same name in the class and the database for a field.

The members must be inserted into the properties member, which is an associative array, using the name of the member as the key name. If you look at the API of ezcPersistentObjectDefinition it also has a property named 'columns' which is the same array as the 'properties' except it is mapped on the column names instead of the property names. This reverse mapping is set up by the ezcPersistentCodeManager.

Finally we return the complete definition. Your definition will not work unless you return it to the manager.

To make the definition work with the ezcPersistentCodeManager it must be put in a separate PHP file and given the name of the class in lowercase letters. In our example it should be put in a file named person.php.

The session object

The session object is in charge of the actual loading and saving of persistent objects. A session can be created simply by instantiating it:

1. <?php
2. $session = new ezcPersistentSession(
3. ezcDbInstance::get(),
4. new ezcPersistentCodeManager( "path/to/definitions" )
5. );
6. ?>

The session takes two arguments: a pointer to the database instance to use and the manager it should use to retrieve persistent object definitions. We are using the ezcPersistentCodeManager which loads the definitions directly from file. You should point it to the location where you saved the person.php file.

While it is possible to create a new session each time you want to manipulate a persistent object you will probably want to use the same session each time. This functionality can be achieved by wrapping the session in a singleton class.

Creating and updating an object

Creating a new Person object and making it persistent is straight forward:

1. <?php
2. $object = new Person();
3. $object->name = "Guybrush Threepwood";
4. $object->age = 31;
6. $session->save( $object );
7. ?>

This code saves our newly created object to the database and generates an id for it. The id is set to the id property of the object. Since Guybrush is our first person he will get the identifier 1.

Of course, the age of Guybrush Threepwood is the source of much debate and most probably he is younger than 31. To make the change simply edit the object and tell the session to update it.

1. <?php
2. $object->age = 25;
3. $session->update( $object );
4. ?>

Note that we used update() to store the object this time. This is because we want to trigger an UPDATE query instead of an INSERT query.

Finding objects

There are several ways to retrieve persistent objects from the database. The simplest is to fetch one object by its identifier.

1. <?php
2. $object = $session->load( 'Person', 1 );
3. ?>

This code retrieves the Guybrush object created above.

If you have stored a lot of persistent objects to the database and you want to retrieve a list you can use the find method. The find method requires a query parameter which you can retrieve from the session first.

1. <?php
2. $q = $session->createFindQuery( 'Person' );
3. $q->where( $q->expr->gt( 'age', 15 ) )
4. ->orderBy( 'full_name' )
5. ->limit( 10 );
6. $objects = $session->find( $q, 'Person' );
7. ?>

This code will fill fetch a maximum of 10 Person objects older than 15 years sorted by their names.

The find() method will fetch the complete result set and instantiate it for you. This is not desirable if you are fetching large numbers of objects and you want it to be fast and efficient. For this you can use the fetchIterator() method:

1. <?php
2. $q = $session->createFindQuery( 'Person' );
3. $q->where( $q->expr->gt( 'age', 15 ) )
4. ->orderBy( 'name' )
5. ->limit( 10 );
6. $objects = $session->findIterator( $q, 'Person' );
8. foreach( $objects as $object )
9. {
10. // ...
11. }
12. ?>

This code will produce the same result as the first find() example. However, only one object will be instantiated and the data will be transfered from the database only when it is needed.

Deleting objects

The easiest way to delete persistent objects is to use the delete method() on the session:

1. <?php
2. $object = $session->load( 'Person', 1 );
3. $session->delete( $object );
4. ?>

Of course, you can only delete instantiated objects this way. If you want to delete an object or a whole series of objects that are not instantiated you can use the deleteFromQuery() method:

1. <?php
2. $q = $session->createDeleteQuery( 'Person' );
3. $q->where( $q->expr->gt( 'age', 15 ) );
4. $session->deleteFromQuery( $q );
5. ?>

When executed the above code will remove all persons older than 15 years old from the database.

ezcPersistentSequenceGenerator

The sequence generator relies on the PDO::lastInsertId() method to retrieve the IDs for newly created persistent objects.

It is recommended to use auto_increment id columns for databases supporting it. This includes MySQL and SQLite. Other databases need to use a sequence. E.g for PostgreSQL the person table definition should look like:

CREATE TABLE persons
(
  id integer unsigned not null,
  full_name varchar(255),
  age integer,
  PRIMARY KEY (id)
);
CREATE SEQUENCE person_seq START 1;

If your database requires you to use a sequence this parameter should be provided to the ezcPersistentSequenceGenerator in the mapping definition.

1. <?php
2. $def->idProperty->generator = new ezcPersistentGeneratorDefinition(
3. 'ezcPersistentSequenceGenerator',
4. array( 'sequence' => 'person_sequence' )
5. );
6. ?>

ezcPersistentCodeManager

This is currently the only manager available. It simply reads the definition from a file named the same as the class from the specified directory. It does not perform any error checking on the definition and simply assumes that it is correct.

Extending the definition loader

It is very easy to create your own definition loader. Simply extend the ezcPersistentDefinitionManager abstract class and implement the fetchDefinition method:

1. <?php
2. class ezcPersistentCodeManager extends ezcPersistentDefinitionManager
3. {
4. public function fetchDefinition( $class )
5. {
6. }
7. }
8. ?>

The fetchDefinition() method should create the definition structure for the requested class or throw an exception