eZPersistentObject allows for data persistence by using a database. It is the recommended way of using additional database tables in eZ publish. Classes derived from eZPersistentObject gain initialization, fetching, listing, moving, storing and deleting for free as well as attribute access. The new class must have a constructor which takes one parameter called $row and pass that this constructor

class MyClass extends eZPersistentObject
{
    function MyClass( $row )
    {
        $this->eZPersistentObject( $row );
    }
}

Defining the class's attributes

All classes derived from eZPersistentObject must re-implement the definition() function. It should return an array with structure similar to the following example:

function definition() {
    return array(
        "fields" => array( 
            "id" => array(
                "name" => "id",
                "datatype" => "integer",
                "default" => 0,
                "required" => true ),
            "value1" => array(
                 "name" => "Value1",
                 "datatype" => "string",
                 "default" => "",
                 "required" => false ),
            "average" => array(
                "name" => "id",
                "datatype" => "integer",
                "default" => 0,
                "required" => true ) ),
        "keys" => array( "id" ),
        "function_attributes" => array(
             "value1_length" => "value1Length" ),
        "set_functions" => array(
             "average" => "setAverage" ),
        "increment_key" => "id",
        "class_name" => "MyClass",
        "name" => "myclass_table"
    );
}

This is a slightly contrived example that should serve to illustrate what is going on. The array has several sub-arrays. The first is "fields" - this is an array, the keys to which are the names of the class attributes, as well as the names of the columns in the database table. The value for each key is another array, which contains a few values:

• name - the name of the object variable which the value of the attribute should be stored in
• datatype - the type of data to be stored. Known valid values here include 'integer', 'string', and 'float', and perhaps more. eZPersistentObject is not strict about the datatype here; for example the object variable might contain an array and it can be accessed as an array even when the datatype is 'string'. You even can specify non-existing datatypes like "asdf" and it will still return the value of the object variable. Therefore the datatype has more an informational purpose than functional.
• required - is this a required field? This can be true or false.
• default - Optional default value for the field if a value is not supplied.

The next value is the "keys" array. This is an array that indicates the values to be used to generate a unique ID for this object - generally if you have an auto-incrementing database column you can put it here.

Next we have the "set_functions" associative array. This is optional. The keys to this array are the names of attributes which should not be set directly, but should be set by a function inside the class. The value is the name of the function. This function should expect one parameter, which is a value to be used in setting the actual attribute value.

The "function_attributes" array defines attributes which are not stored values, but are instead generated using a class function. This is useful where you need to perform some processing before returning the value. To an outside user of this class, there is no difference between accessing an actual attribute and a function attribute.

The "increment_key" specifies a database column where the value automatically increments after every insert.

The "class_name" specifies the name of the class to map the object to (generally the same as the class in which you are redefining the definition function).

Finally, "name" is the name of the database table. There are other options which are used for defining foreign key relations too but their use is not clear at present.

Using your class

If you have successfully defined your class and implemented any methods required, you will be able to use it as follows:

• Create a new class using "new MyClass()"
• Fill its attributes using the setAttribute() method
• Store the object using the store() method
• Retrieve its attributes using the attribute() method
• Obtain a list of all its attributes using the attributes() method
• Fetch objects from the database using fetchObject(), or lists of objects using fetchObjectList()
• Remove objects using the remove() method

These methods are currently better explained using the eZPersistentObject page on PubSVN.

External resources

• OR condition in eZPersistentObject::fetchObject