MidCOM Database Abstraction Layer

From MidgardWiki

MidCOM's Database Abstraction Layer (DBA) provides an interface to MgdSchema functionality of the Midgard Core. They are part of the MidCOM Base Classes an act like a wrapper and provide Midgard functionality to the MidCOM framework. Aside from this, there is also a MidCOM Legacy Database Abstraction Layer which provides legacy accesss to certain objects.

Internally, this is facilitated by a code generator which produces the necessary base classes from MgdSchema XML files. These have to be extended in the respective MidCOM Component to get a PHP object representing the database table.

Main Features

One important part of this layer is midcom_core_querybuilder, which provides access to the Midgard MySQL Database via Query Builder. 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.

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();

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);
    }
}