The Resource Class

To avoid the need for direct interaction with the database (and therefore allow the use of myriad databases within the product) all DB interaction has been abstracted through the use of several 'Resource' classes. Each of these classes represents a single type of resource in the system that one might want to interect with, a table, user, or field type, for example.

These resource classes contain several helpful functions designed to facilitate any need to create / modify / delete information within the database(s).

1. Resource Class Standard Functions

While some resource classes will provide specific functionality that only applies to themselves, there are some established standard functions that you can expect all resource classes to have. These include: 

load($args = array()) Load accepts an array which should contain a unique identifier (either an ID or Key) specifying which specifc instance of the resource to load information for. See individual resource class documentation to see which identifiers a given class supports. 

get*() Each readable property of resource can be accessed by a get function named for that property. All class methods are named in "camel case" with not spaces, beginnning with a lowe case letter. So, for example, to get the Name property for a Source object, you would call $source_obj->getName(); This will return the value of the property. 

set*($val) Each writeable property of a resource can be set by a set function following the same naming scheme as the get functions. With few exceptions, everything readable property that is not a unique identifier is writeable. 

commit() The commit function is used to save changes in a resource to the DB. If load() has been previously called on a resource, calling commit() will update the appropriate database entr(y/ies) for the loaded resource. If load() has not been previously called, calling commit() will create the appropriate new entr(y/ies) in the database. It will also subsequently perform a load() so that unqique identifiers for the new resource will be accessibly via the get*() functions. 

remove() Calling remove() after load() has been called will delete the appropriate entr(y/ies) for the resource from the database. If load() has not been called, remove() will have no effect. 

search($args=array()) The search function accepts an associative array, the keys of which are the names of properties that you wish to search for resources based on. The naming scheme for properties is lowercase, with underscores in place of spaces. See specific class definitions for a list of properties you can search using. The value for each key can be either a single value, or an array. If a single value is specified, only resources where the property specified equals that will be found. If it is an array, the first value should be a code specifying the type of comparison to perform, and the second should be the value to compare. Valid codes are:

  • eq (eqals)
  • ne (does not equal)
  • in (is one of these values : value should be a comma seperated list)
  • ni (is not one of these values : value should be a comma seperated list)
  • gt (greater than)
  • lt (less than)
  • bw (begins with)
  • ew (ends with)
  • cn (contains)

The search function will return an array of associative arrays, each associative array representing one resource that matched the search criteria and containing a key for each property.

2. The Resource Factory

To ResourceFactory class is used to instantiate Resource objects. Given a resource type & a database object (see dbo), it will return an object of the appropriate resource type & db type.

The resource factory can be instantiated, in which case the database object should be passed in an array to the construct function. Once instantiated, the getResource function will return instantiated resource objects.  getResource() takes two parameters. The first is a string specifying the type of resource desired. The second is an array of optional arguments. An example is below.

$factory = new ResourceFactory(array('dbo'=>$dbo));
$source_obj = $factory->getResource('Source',array());

The getResource function can also be called statically, in which case the database object should be passed to the function call. The below example has the same effect as the above.

$source_obj = ResourceFactory::getResource('Source',array('dbo'=>$dbo));

3. Auto Loading Resources with getResource

When calling ResourceFactory::getResource() either statically OR on an instantiated ResourceFactory object, a unique identifier can be passed in the array of arguments. In this case, load() will be called internally on the instantiated resource object before it is returned, so the this:

$source_obj = ResourceFactory::getResource('Source',array('dbo'=>$dbo));

Is equivalent to:

$source_obj = ResourceFactory::getResource('Source',array('dbo'=>$dbo,'source_id'=>24));