MidCOM Database Abstraction Layer

From OpenPSA Wiki

MidCOM's Database Abstraction Layer (DBA) provides an interface to MgdSchema functionality of the Midgard storage backend. They are part of the MidCOM Base Classes an act like a wrapper and provide Midgard functionality to the MidCOM framework.

Internally, this is imlemented with the midcom_core_dbaobject base class that acts as a decorator to Midgard objects. DBA classes have to extend this base class to get a PHP object representing the database table row.

[edit] Main Features

One important part of this layer is midcom_core_querybuilder, which provides access to the storage backend. In all DBA-based classes, methods like new_query_builder() and functionality like the MidCOM ACL system is automatically available.

There are also a number of "event handler" functions that are automatically triggered when a DBA object is updated, created or deleted. One of them is called before the operation, another one after it is completed. For deletion, they look like this:

function _on_deleting()
{
   //your code here
   //you can use $this to operate on the object in question
   return $proceed //false cancels the operation, true causes it to proceed
}
 
function _on_deleted()
{
   //your code here. 
   //you can use $this to operate on the object in question
}

Apart from these methods, the more generic MidCOM Watches allow a Component (or the MidCOM core) to react to changes done to other objects as well, for example a Midgard Replicator run can be triggered when an object is updated or deleted.

[edit] Example

If you have a database table mytable consisting of two columns, mystring and myfloat, and a correctly defined Mgdschema file to go along, the DBA system will provide you with a PHP object with both columns as properties and all the standard methods, so code like this is possible:

//create a new entry in the database:
$object = new mytable_dba_class();
$object->mystring = "something";
$object->myfloat = 2.3456;
$object->create();
 
//retrieve entries from the db:
$qb = mytable_dba_class::new_query_builder();
$qb->add_constraint('myfloat', '>', 3);
$qb->add_order('mystring');
$entries = $qb->execute();

[edit] Creating a Component with a Custom Object Schema

A small howto from the midgard-users forum:

create component skeleton using for example the scaffold
create mgdschema.xml
symlink the .xml from MIDGARD_PREFIX/share/midgard/schema/ using the component name as filename.
stop apache
run midgard-schema database_name to get the SQL imported and then metadata etc columns added
start apache
in manifest.inc add 'class_definitions' => Array('midcom_dba_classes.inc'),
edit/create file midcom_dba_classes.inc (in the config directory. See the following example of a class

array(
    'table' => 'org_routamc_positioning_location',
    'old_class_name' => null,
    'new_class_name' => 'org_routamc_positioning_location',
    'midcom_class_name' => 'org_routamc_positioning_location_dba'
),

in component root create my_class.php, below is a basic example based on the definition above:

class org_routamc_positioning_location_dba extends __org_routamc_positioning_location_dba
{
    function org_routamc_positioning_location_dba($id = null)
    {
        return parent::__org_routamc_positioning_location_dba($id);
    }
}