Author: Frederik Holljen
Date: 2006-01-25 15:32:05 +0100 (Wed, 25 Jan 2006)
New Revision: 2026
Log:
Add tutorial, remove old tutorial from session.
Added:
packages/PersistentObject/trunk/docs/tutorial.txt
Modified:
packages/PersistentObject/trunk/src/generators/sequence_generator.php
packages/PersistentObject/trunk/src/persistent_session.php
Added: packages/PersistentObject/trunk/docs/tutorial.txt
===================================================================
--- packages/PersistentObject/trunk/docs/tutorial.txt 2006-01-25 13:09:16 UTC
(rev 2025)
+++ packages/PersistentObject/trunk/docs/tutorial.txt 2006-01-25 14:32:05 UTC
(rev 2026)
@@ -0,0 +1,333 @@
+eZ components - PersistentObject
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. contents:: Table of Contents
+
+Introduction
+============
+Persistent Object provides object persistence using a database for PHP
+5. Persistent Object relies uses the Database components to provide database
+abstraction. It does not rely on code generation and does not force a specific
+inheritance structure to work.
+Persistent Object is built to be fast and flexible allowing you to build your
+persistent classes in the same way as any other class in your application.
+
+Class overview
+==============
+
+This section gives you an overview of the main classes of Persistent Object.
+
+ezcPersistentSession
+ ezcPersistentSession is the main API for interaction with the object
+ persistence. Loading, saving and deleting persistent objects is done through
+ this class.
+
+Basic Usage
+===========
+
+This chapter describes typical usage of the Persistent Object package with a
+single persistent class using MySQL as the persistence storage.
+
+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:
+
+::
+ class Person
+ {
+ private id = null;
+ public name = null;
+ public age = null;
+
+ public function getState()
+ {
+ $result = array();
+ $result['id'] = $this->id;
+ $result['name'] = $this->name;
+ $result['age'] = $this->age;
+ return $result;
+ }
+
+ public function setState( array $properties )
+ {
+ foreach( $state as $key => $value )
+ {
+ $this->$key = $value;
+ }
+ }
+ }
+
+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: ::
+
+ <?php
+ $def = new ezcPersistentObjectDefinition();
+ $def->table = "persons";
+ $def->class = "Person";
+
+ $def->idProperty = new ezcPersistentObjectIdProperty;
+ $def->idProperty->columnName = 'id';
+ $def->idProperty->propertyName = 'id';
+ $def->idProperty->generator = new ezcPersistentGeneratorDefinition(
+ 'ezcPersistentSequenceGenerator' );
+
+ $def->properties['name'] = new ezcPersistentObjectProperty;
+ $def->properties['name']->columnName = 'full_name';
+ $def->properties['name']->propertyName = 'name';
+ $def->properties['name']->propertyType =
ezcPersistentObjectProperty::PHP_TYPE_STRING;
+
+ $def->properties['age'] = new ezcPersistentObjectProperty;
+ $def->properties['age']->columnName = 'age';
+ $def->properties['age']->propertyName = 'age';
+ $def->properties['age']->propertyType =
ezcPersistentObjectProperty::PHP_TYPE_INT;
+
+ return $def;
+ ?>
+
+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: ::
+
+ $session = new ezcPersistentSession( ezcDbInstance::get(),
+ new ezcPersistentCodeManager(
"path/to/definitions" ) );
+
+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: ::
+
+ $object = new Person();
+ $object->name = "Guybrush Threepwood";
+ $object->age = 31;
+
+ $session->save( $object );
+
+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. ::
+
+ $object->age = 25;
+ $session->update( $object );
+
+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. ::
+
+ $object = $session->load( 'Person', 1 );
+
+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. ::
+
+ $q = $session->createFindQuery( 'Person' );
+ $q->where( $q->expr->gt( 'age', 15 ) )
+ ->orderBy( 'full_name' )
+ ->limit( 10 );
+ $objects = $session->find( $q, 'Person' );
+
+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: ::
+
+ $q = $session->createFindQuery( 'Person' );
+ $q->where( $q->expr->gt( 'age', 15 ) )
+ ->orderBy( 'name' )
+ ->limit( 10 );
+ $objects = $session->findIterator( $q, 'Person' );
+
+ foreach( $objects as $object )
+ {
+ ...
+ }
+
+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: ::
+
+ $object = $session->load( 'Person', 1 );
+ $session->delete( $object );
+
+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: ::
+
+ $q = $session->createDeleteQuery( 'Person' );
+ $q->where( $q->expr->gt( 'age', 15 ) );
+ $session->deleteFromQuery( $q );
+
+When executed the above code will remove all persons older than 15 years old
+from the database.
+
+
+Identifier generation
+=====================
+
+All persistent objects are required to have an identifier field. The identifier
+generation algorithm defines how the system will generate IDs for new
+objects. This chapter describes the available generators.
+
+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. ::
+
+ $def->idProperty->generator = new ezcPersistentGeneratorDefinition(
'ezcPersistentSequenceGenerator',
+ array(
'sequence' => 'person_sequence' ) );
+
+
+Definition loaders
+===================
+
+The session object needs to be able to fetch the persistent object
+definitions in order to function properly. The task of fetching the definitions
+is performed by a definition loader which is provided to the session when it is
+instantiated.
+
+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: ::
+
+ class ezcPersistentCodeManager extends ezcPersistentDefinitionManager
+ {
+ public function fetchDefinition( $class )
+ {
+ }
+ }
+
+The fetchDefinition() method should create the definition structure for the
+requested class or throw an exception
+
+
+..
+ Local Variables:
+ mode: rst
+ fill-column: 79
+ End:
+ vim: et syn=rst tw=79
Property changes on: packages/PersistentObject/trunk/docs/tutorial.txt
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: packages/PersistentObject/trunk/src/generators/sequence_generator.php
===================================================================
--- packages/PersistentObject/trunk/src/generators/sequence_generator.php
2006-01-25 13:09:16 UTC (rev 2025)
+++ packages/PersistentObject/trunk/src/generators/sequence_generator.php
2006-01-25 14:32:05 UTC (rev 2026)
@@ -12,8 +12,25 @@
/**
* Generates IDs based on the PDO::lastInsertId method.
*
+ * It is recommended to use auto_increment id columns for databases supporting
+ * it. This includes MySQL and SQLite. Other databases need to create a
sequence
+ * per table.
+ *
+ * auto_increment databases:
+ * <code>
+ * CREATE TABLE test
+ * ( id integer unsigned not null auto_increment, PRIMARY KEY (id ));
+ * </code>
+ *
+ * For none auto_increment databases:
+ * <code>
+ * CREATE TABLE test ( id integer unsigned not null, PRIMARY KEY (id ));
+ * CREATE SEQUENCE test_seq START 1;
+ * </code>
+ *
* This class reads the parameters:
- * - sequence - The name of the database sequence keeping track of the ID.
This field should be ommited for MySQL.
+ * - sequence - The name of the database sequence keeping track of the ID.
This field should be ommited for databases
+ * supporting auto_increment.
*
* @package PersistentObject
* @access private
Modified: packages/PersistentObject/trunk/src/persistent_session.php
===================================================================
--- packages/PersistentObject/trunk/src/persistent_session.php 2006-01-25
13:09:16 UTC (rev 2025)
+++ packages/PersistentObject/trunk/src/persistent_session.php 2006-01-25
14:32:05 UTC (rev 2026)
@@ -8,13 +8,6 @@
* @license http://ez.no/licenses/new_bsd New BSD License
*/
-// * Each persistent object must have an ID. The ID field should never be
manipulated
-// * manually.
-// * Persistent object fields should default to null for uninitialized values.
-// * Persistent object does currently not check if a field actually contains
data of
-// * the correct type. If the data is of the wrong type the resulting query
will fail.
-// *
-
/**
* ezcPersistentSession is the main runtime interface for manipulation of
persistent objects.
*
@@ -22,146 +15,6 @@
* 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.
*
- * Each persistent object must have a definition in the form of a
ezcPersistentObjectDefinition.
- * Definitions are stored and handled with the ezcPersistentCodeManager.
- *
- * The following example shows you all steps to get started with persistent
objects.
- *
- * Let's assume that we have a database table like this in MySQL:
- * <code>
- * CREATE TABLE persons
- * (
- * id integer unsigned not null auto_increment,
- * full_name varchar(255),
- * age integer,
- * PRIMARY KEY (id)
- * ) TYPE=InnoDB;
- * </code>
- *
- * We would like to map this person to an object in PHP. First we need to
define
- * a class that holds one person:
- * <code>
- * class Person
- * {
- * private id = null;
- * public name = null;
- * public age = null;
- *
- * public function getState()
- * {
- * $result = array();
- * $result['id'] = $this->id;
- * $result['name'] = $this->name;
- * $result['age'] = $this->age;
- * return $result;
- * }
- *
- * public function setState( $properties )
- * {
- * foreach( $state as $key => $value )
- * {
- * $this->key = $value;
- * }
- * }
- * }
- * </code>
- * Since we will map the id field to the primary key auto_increment value it
is important
- * that it defaults to null. You can set default values on the other fields as
you like.
- * The setState and getState methods are used by the ezcPersistentSession when
storing
- * and retrieving persistent objects.
- * For simplicity we have made the name and age properties public. In a real
application
- * you would of course have access to these through real properties or through
access
- * methods.
- *
- * In order to make our class a real persistent object we need to create a
mapping between
- * the database table and the class. This is done with the
ezcPersistentObjectDefinitionClass.
- * We will use the ezcPersistentCodeManager to manage our definitions. It
requires each
- * definition to be in a separate file that has the same name as our class in
lowercase.
- * person.php:
- * <code>
- * <?php
- * $def = new ezcPersistentObjectDefinition();
- * $def->table = "person";
- * $def->class = "Person";
- *
- * $def->idProperty = new ezcPersistentObjectIdProperty;
- * $def->idProperty->columnName = 'id';
- * $def->idProperty->propertyName = 'id';
- *
- * $def->idProperty->generator = new ezcPersistentGeneratorDefinition(
'ezcPersistentSequenceGenerator',
- * array( /
*'sequence' => 'person_sequence'* / ) );
- *
- * $def->properties['name'] = new ezcPersistentObjectProperty;
- * $def->properties['name']->columnName = 'full_name';
- * $def->properties['name']->propertyName = 'name';
- * $def->properties['name']->propertyType =
ezcPersistentObjectProperty::PHP_TYPE_STRING;
- *
- * $def->properties['age'] = new ezcPersistentObjectProperty;
- * $def->properties['age']->columnName = 'age';
- * $def->properties['age']->propertyName = 'age';
- * $def->properties['age']->propertyType =
ezcPersistentObjectProperty::PHP_TYPE_INT;
- * return $def;
- * ?>
- * </code>
- * Each persistent object is required to have an id field. This id field must
be an integer
- * both in PHP and in the database. If you look at the API of
ezcPersistentObjectDefinition
- * it also has a property named 'columns' which is a reverse mapping of the
'properties'
- * property on the column name. We don't need to define it ourselves as it is
automatically
- * set up by ezcPersistentCodeManager.
- *
- * It is time to try out our creation. In all applications using persistent
objects
- * we need to initialize the session object:
- * <code>
- * $session = new ezcPersistentSession( ezcDbInstance::get(),
- * new ezcPersistentCodeManager(
"path/to/definitions" ) );
- * </code>
- * This sets up the session to work on the default database instance. The code
manager will
- * feed the session with persistent object definitions. "path/to/definitions"
must of course be
- * replaced with the path where you put person.php.
- *
- * Lets make a new persistent object and store it to the database:
- * <code>
- * $object = new Person();
- * $object->name = "John Doe";
- * $object->age = 31;
- *
- * $session->save( $object );
- * </code>
- * 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.
- * If we want to update the same object with new data we can continue to work
on the same
- * object:
- * <code>
- * $object->age = 32;
- * $session->update( $object );
- * </code>
- * 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. Similarly to update and save we
also have delete.
- * To retrieve a stored persistent object use one of the load methods:
- * <code>
- * $object = $session->load( 'Person', 1 );
- * $session->delete( $object );
- * </code>
- * Loads the object with id 1 and deletes it.
- *
- * 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.
- * <code>
- * $q = $session->createFindQuery( 'Person' );
- * $q->where( $q->expr->gt( 'age', 15 ) )
- * ->orderBy( 'full_name' )
- * ->limit( 10 );
- * $objects = $session->find( $q, 'Person' );
- * </code>
- * This code will fill the $objects variable with 10 Person persistent objects
where
- * age is higher than 15 sorted on their name.
- *
- * Note that this beta release requires you to use the table and column names
when building the
- * query. In the final release you will be able to use the persistent object
name and the
- * property names instead.
- *
- * @see ezcPersisentObject
* @todo if there is a high probability that an exception was caused by
* a bad definition or by a bad set/getState method we should run a
checker or some sort.
* @todo - remove required and default value fields in definition for now
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
