CiviCRM Architecture

We are documenting various aspects of CiviCRM Architecture in series of Blog posts. Check out the link below if you are a developer or integrator interested in learning more about how CiviCRM is built.

http://civicrm.org/architecture

Database structure

There are several copies of the ERD 'around the place' - most recent at time of writing was v3.1 of the DB. However, I couldn't find anything that explains how the DB is generated from the XML files and how it flows through to the DAO & BAO objects so here is my cut at it:

XML files

The XML files that describe the CiviCRM database are located in Civicrm/xml/Schema. All the folders within this directory also have folders in the main CRM folder which contain a DAO folder and generally a BAO folder too. There are two exceptions - 'Auction' and 'SMS' do not contain 'DAO' folders -for reasons which will become clear.

So, looking in CiviCRM/xml/Schema/Pledge we see 4 files:

files.xml

Pledge.xml

PledgePayment.xml

PledgeBlock.xml

files.xml is just a list of the other files. Each of the others represents a table in the Database. The XML files describe the database and are used to build both the DAO files and the new database sql generation script.

The XML describes fields, foreign keys and indexes -an example of a field definition is:

<field>
       <name>amount</name>
       <uniqueName>pledge_amount</uniqueName>
       <title>Total Pledged</title>
       <type>decimal</type>
       <required>true</required>
       <import>true</import>
       <comment>Total pledged amount.</comment>
       <add>2.1</add>
</field>

The field 'amount' in the table 'pledge' has a unique name to distinquish it from fields in other tables (e.g. contribute) with the same field. This isn't consistent in all tables and I am trying to find out the reason / rules for this. Also, I presume 'import' means the field is exposed for .... imports?.

We can see that the above 'pledge_amount' field was added in CiviCRM v2.1. Note that if you look at the XML for SMS the table description starts:

<table>
<base>CRM/SMS</base>
<class>History</class>
<name>civicrm_sms_history</name>
<comment>SMS History can be linked to any object in the application.</comment>
<add>1.4</add>
<drop>2.0</drop>

i.e. the tabls has been dropped - hence the lack of a DAO object for it.

DAO files

The DAO files live in the relevant DAO folder - e.g. CiviCRM/Pledge/DAO and there is one file for each of the xml files we looked at earlier. These files are built on the fly when CiviCRM is packaged from the XML files which is why you won't see them if you checkout CiviCRM from SVN. (You can create them using the script xml/Gencode.php if you need to - e.g. if running from SVN).

The DAO object generated has

a property for each field using the actual field name, not the unique name
A links function which retrieves the links to other tables (off the foreign keys)
An import function & an export function for ?
A fields function which returns an array of fields for that object keyed by the field's unique name. Looking again at the field 'pledge.amount' we see
A couple of functions to define the labels for enumerated fields

'pledge_amount' => array(
                    'name' => 'amount',
                    'type' => CRM_Utils_Type::T_MONEY,
                    'title' => ts('Total Pledged') ,
                    'required' => true,
                    'import' => true,
                    'where' => 'civicrm_pledge.amount',
                    'headerPattern' => '',
                    'dataPattern' => '',
                    'export' => true,
                ) ,

Note that the key is the unique name but the name field is the field's name and the 'where' field shows the mysql description of it. We also see the data type and ?whether it is imported/ exported?

BAO

BAO files are 'hand-crafted' rather than generated but have a few standard functions. Looking at pledge again we see:

Add & Create. Add calls just the creation of the pledge itself whereas 'create' calls subsidiary functions such as creating activities & populating custom fields. The APIs call 'Create' which then calls 'Add' as well as other associated functions