DBO Core API

DBO stands for Database Object and it is integral part of genie ORM framework. More...

Classes
class	dbo_manager
	Database objects system manager. More...
class	dbo_session
	DBO session. More...
class	dbo_def
	DBO entity type definition. More...
class	dbo_attr_def
	DBO entity attribute type definition. More...
class	dbo_bag_def
	DBO entity bag type definition. More...
class	dbo
	Base DBO class. More...
class	dbo_bag
	DBO bag is container object that is used to implement entity relations. More...
class	dbo_extension
	Base DBO extensions. More...
class	dbo_registry
	DBO information registry. More...

---

Detailed Description

DBO stands for Database Object and it is integral part of genie ORM framework.

In this documentation DBO refers to instances of classes derived from dbo. You can find list of these classes on DBO Model API page. This documentation focuses on usage of DBO in PHP application. Information on how to generate DBO/SQL code for ORM can be found in genie documentation.

Next section will show you the most common uses of DBO API. Following sections, will discuss DBO design.

Quick'n'dirty coding HOWTO

You probably don't (and shouldn't) care about inner design of DBO, so we will start with examples of DBO use. Following data model will be used in these examples:

 model "DBO Example" "Author";

 entity article {
   title text;
   content *text [ dbo_default "Empty!" ];

   parts ==> *part [ordered];
   tags --> tag [shared];
 }

 entity part {
   content *text;
 }

 entity tag {
   name text;
 }

You will learn how to:

• [1] start new session,
• [1] create new DBO,
• [1] set DBO attributes,
• [2] get DBO from DB,
• [2] read attributes,
• [2] update DBO in DB,
• [2] remove DBO from DB,
• [3] add new objects to the dbo_bag,
• [3] get objects from the dbo_bag,
• [3] reorder objects in the dbo_bag,
• [3] remove objects from dbo_bag,
• [4] perform validity checks.

Initialize DB connection:

 $db = new database('pgsql:dbname=name;host=localhost', 'username', 'password');

[1] Create and persist DBOs:

 // Initial session is started automatically when needed. You only need to
 // start new session explicitely like this if you know that other session is
 // already active and you want new one.
 dbo_manager::start_session();

 // Create new article DBO. Article is automatically associated with active
 // session.
 $dbo1 = new article();

 // Set entity attributes:
 $dbo1->title = 'My Article';
 $dbo1->content = 'Some content';

 // You may also set attributes using setter: (this is deprecated way)
 $dbo1->set_title('My Article');

 // Generic attribute setter is also available:
 $dbo1->attr_set('title', 'My Article');

 // You can also replace above calls with single line:
 $dbo1 = article::create('My Article', 'Some content');

 // Commit changes you made in this session to DB.
 dbo_manager::get_session()->commit();

[2] Get and manipulate with DBOs:

 dbo_manager::start_session();

 // Create new article DBO. Article is automatically associated with active
 // session.
 $dbo1 = article::get(1);

 // Print DBO attributes:
 echo $dbo1->title;
 echo $dbo1->content;

 // To quickly print whole DBO state, you can use dbo::dump() method:
 echo $dbo1->dump();

 // Update title and persist changes:
 $dbo1->title = 'New Title';
 dbo_manager::get_session()->commit();

 // To remove DBO from DB, you must first get it:
 article::get(1)->remove();
 dbo_manager::get_session()->commit();

[3] Manipulate with dbo_bag contents, that is, create relations between DBOs:

 dbo_manager::start_session();

 // Add 2 new parts to existing article:
 $article = article::get(1);
 $part1 = $article->parts->create();
 $part1->content = 'Part 1 content';
 $part2 = $article->parts->create();
 $part2->content = 'Part 2 content';

 // Move part1 after part2:
 $article->parts->move_after($part1, $part2);

 // Find and associate existing tags with article:
 $tags = tag::query("WHERE name LIKE ?", '%'.0$prefix);
 foreach ($tags as $tag)
   $article->tags->add($tag);

 // Add new 'php' tag:
 $article->tags->add(tag::create('php'));

 // Persist changes:
 dbo_manager::get_session()->commit();

 // List article parts and tags:
 foreach (article::get(1)->parts->get_iterator() as $part)
   echo $part->title . "\n";
 foreach (article::get(1)->tags->get_iterator() as $tag)
   echo $tag->name . "\n";

 // Remove association with 'php' tag:
 foreach ($article = article::get(1)->tags->get_iterator() as $tag)
   if ($tag->name == 'php')
     $article->tags->remove($tag);

 // Persist changes:
 dbo_manager::get_session()->commit();

[4] Validity checking:

 dbo_manager::start_session();

 // Do some changes to DBOs:
 ...

 // Try to commit, if commit fails, we will dump invalid DBOs:
 if (!dbo_manager::get_session()->commit())
   dbo_manager::get_session()->dump(true);

 // Now a bit finer approach. You probably iterate over DBO attributes so that
 // you can display them to the user. For each attribute you can check if
 // some error messages are associated with it.
 if ($msgs = $article->get_messages())
   echo "whole entity errors: " . implode(", ", $msgs);
 foreach ($article->def->attrs as $attr_def)
   if ($msgs = $article->attr_get_messages($attr_def->name))
     echo $attr_def->name . " error: " . "(" . implode(", ", $msgs) . ")\n";
 foreach ($article->def->bags as $bag_def)
   if ($msg = $article->{$attr_def->name}->message)
     echo $bag_def->name . " bag error: " . $msg . "\n";

High-level design overview

Todo: