What does the new API offer? – an Overview

The new API allows you to return a database table as an object and execute different methods on this object. For example, if you want to have a customer object with the attributes ID, name, and name suffix, you can get it by using the following call:

$lrKunde = LimbasRecord::model('KUNDEN', array('ID', 'NAME', 'NAME_ZUSATZ'));

In general, the call is:

$object = LimbasRecord::model($tableName, $attributes=null);

It returns a static instance of the named LimbasRecord class, in the example Customers, where the class methods can be called afterwards.

At such an object instance not only methods can be executed, but also objects linked with this object can be returned or new objects can be derived from this object.

For example, if you want to contact a customer, first get the Customer object with the attributes ID and Contacts. In the next step, you use the findById() function to get the desired customer and then the contacts.

$lrCustomer = LimbasRecord::model('CUSTOMERS', array('ID', 'Contacts'));
$customer = $lrCustomer->findById(1);
$relation = $customer->CONTACTS();

Another part of the new API is the ability to create logging protocols. You have the option to have the output returned as simple logging strings, to have the logging strings output to a file or to have them processed as a web edition.

Also representation of the echo output was extended for objects.

Sources of the API

The source code of the API can be found in the directory limbas_src → extra → lmbObject. It is divided into three packages:

• base: contains the abstract class LimbasComponent, which deals with some of the magic methods, and the class LimbasException.
• db: contains the classes LimbasRecord and LimbasRelation, both inheriting from the class LimbasComponent and the class LimbasRecordException inheriting from the class LimbasException. The LimbasRecord class is the interface to the database, and the LimbasRelation class represents the link between two database tables.
• Log: contains the interface LimbasLogRoute, the classes LimbasPlainLogRoute, LimbasWebLogRoute and LimbasFileLogRoute, which implement the interface LimbasLogRoute and output the log entries either “untreated”, prepare for the web or save to a file and the class LimbasLogger in which the individual logging entries are collected.

LimbasRecord

Description of the main methods of the class LimbasRecord

The following are the main methods of the LimbasRecord class that are possible for use in an extension.

public static function model($tableName, $attributes=null)

The central method of the class is public static function model ($tableName, $attributes=null). It returns a static model of the named Limbas class. The class methods can then be called at this static class instance. The parameters require the table name and the attributes to be used.

public function findAll($criteria)

With the findAll($criteria) function, all data records that match the given criteria can be queried at the determined class instance. See the following example for this:

$lrKunde = LimbasRecord::model('KUNDEN', array('ID', 'NAME', 'NAME_ZUSATZ'));
$criteria = array('limit' => 3, 'page' => 18, 'sort' => array('NAME' => LimbasRecord::SD_ASC));
$kunden = $lrKunde->findAll($criteria);
for($i=0; $i<count($kunden); $i++) {
  $kunde = $kunden[$i];
  echo '' . ($i+1) . '. Kunde
echo $kunde; // calls __toString' . $kunde . '
';
}
echo '</div>';

First, the object “customer” is fetched with “model”. The next line defines the criteria for the findAll function. They say that a maximum of three records, page 18, are output, sorted by name in ascending order. Then the function findAll is executed on the object $lrCustomer and the records are returned to $customers. Finally, the fetched records are looped through in a for loop and output with echo. In doing so, the magic method __toString is called internally.

public function findById($id)

The function findById($id) also works accordingly. Here, instead of all records, the record with the id given in is returned.

public function save($runValidation=false, $attributes=null)

The save function saves the object at which the function is called. In the case of a new object, the function insert() is called internally, in the case of an existing update(). The parameter to be passed is, whether a validation should take place and which attributes should be stored, whereby both parameters are optional. The return value of the function is true if the save was successful and false if not.

public function saveRelation($field, $other)

Of course, as well as the object, the relationship between one object and another can also be stored. The field name of the field to be linked and the object to be linked are passed as parameters. The return value of the function is true if the save was successful and false if not.

public function delete()

Of course, an object can not only be saved but also deleted. There is the function delete(), which is simply called on the object to be deleted.

getter-/setter-methods of the class LimbasRecord

In object orientation, the individual attributes are usually accessed via getter and setter methods. Also in the class LimbasRecord there are numerous getter and setter methods to access the attributes. By way of example, the function for returning the “Attributes” is shown here.

public function getAttributes() {
 return $this->attributes;
}

With the exception of the getDefinition($name) function, the getter functions have no parameters that are passed and are always structured according to the function shown. There are the following additional getter functions:

• getAttributeIds()
• getMappings()
• getDefinitions()
• getId()
• getTable()
• getTableId()
• getClassName()
• getFindMetaData().

The setter functions are simple functions, too, like the following example shows:

public function setAttributes($attributes) {
 $this->attributes = $attributes;
}

There are the following additional setter functions:

• setAttributes($attributes)
• setDefinitions($definitions)
• setId($id)
• setLoading($loading).

State queries of class LimbasRecord

Another component of the class LimbasRecord are various state queries, which return true in the positive case, otherwise false. It can be checked, for example, if there is an attribute with the given name “isAttribute($name)” or if the record has changed “isChanged()”. Other status queries are:

• isUsableAttribute($name),
• isRelation($name)
• isFromRelation($name)
• isNew().

Transaction Handling

The startTransaction(), endTransaction(), and rollbackTransaction() functions can easily execute a database action in a transaction. For example, to save a new contact in a transaction, it looks like this:

kontakt = new LimbasRecord('kontakte');
$kontakt->Name = 'Maier';
$kontakt->Vorname = 'Heinz';
LimbasRecord::startTransaction();
$kontakt->save();
LimbasRecord::endTransaction();

The transaction is started with startTransaction() and needs the call endTransaction() on completion.

LimbasRelation

What methods are available for the linked object?

The class LimbasRelation represents the linking of two database objects and contains the functions to make changes to this link. In the following, as for the class LimbasRecord, the most important of these functions are considered for use in an extension.

The LimbasRelation class contains only getter and setter functions and queries that check for the existence of a specific attribute or object, with two exceptions. The other two functions are the addCriteria($name, $value) functions, which adds a “criteria expression” and addObject($object). As the name suggests, addObject($object) adds an object, to be exact, a linked object. The function first creates a logging entry. After checking whether it’s an object of the correct database table, it is added to the list of linked objects in the affirmative. In the negative case, a LimbasRecordException is thrown.

getter-/setter- Functions

The getter functions all have the same structure here as well.

public function getObjects() {
 $this->log('LimbasRelation(' . $this->refId . ', ' . $this->definition['name'] . ').getObjects ' . count($this->objects));
 return $this->objects;
}

In the first step, a log message is written, in the second, an array of the corresponding objects is returned. Apart from the getObjects() shown in the example, there are also the functions

• getStrings()
• getCriteria()
• getAttributes().

The setter functions also essentially all look the same. First, a log message is written, then the objects are replaced.

public function setCriteria($criteria) {
 $this->log('LimbasRelation(' . $this->refId . ').setCriteria(' . var_export($criteria, true) . ')');
 $this->criteria = $criteria;
}

Only the function setObject($objects) differs slightly from this scheme.

public function setObjects($objects) {
 $this->log('LimbasRelation(' . $this->refId . ', ' . $this->definition['name'] . ').setObjects(' . count($objects) . ')');
 $this->objects = array();
 foreach($objects as $object) {
  $this->addObject($object);
 }
}

Here the passed objects are looped through and for each of the objects the function addObject($object) is executed.

Finally, there are the two functions hasObjects() and hasStrings(), which check whether there are objects or strings and return true in the positive case, otherwise false.

Magic Methods

In object-oriented PHP there are so-called “magic methods”. These magic methods are automatically called by PHP for certain actions. They always start with a double underscore, so this notation should not be used for other functions. PHP has the following magic methods:

• __construct()
• __destruct()
• __call()
• __callStatic()
• __get()
• __set()
• __isset()
• __unset()
• __sleep()
• __wakeup()
• __toString()
• __invoke()
• __set_state()
• __clone()
• __autoload()

For a more detailed explanation of magic functions, consider the method __construct(). Each class has it automatically, but it can also be overridden with a new functionality. The following example shows the __construct() method of the LimbasRecord class. As a parameter, it has a table name of Limbas and attributes to use. The method first calls the __construct() method of the inheriting class, then changes the table name to uppercase, saves a log entry, and calls the createAttributes method.

public function __construct($table, $attributes=null) {
 parent::__construct();
 $this->_table = strtoupper($table);
 $this->log('LimbasRecord(' . $this->refId . ').__construct ' . $this->_table);
 $this->createAttributes($attributes);
}

For example, if you want to create a new customer, call $customer = new LimbasRecord(‘customer’); The automatically described constructor __construct() is called and the new class is created.

How does Logging work?

The logging functionality is composed of different classes. First, there is the interface LimbasLogRoute. This is implemented by the classes LimbasFileLogRoute, LimbasPlainLogRoute and LimbasWebLogRoute. In these classes, the log messages for the corresponding output paths, i. File output, simple edition and web edition prepared. The class LimbasLogger takes care of the actual work of the message collection and provides various functions:

• log($str,$level=self::LL_INFO): Logs a string to the logger (with the loglevel LL_INFO)
• trace($str): Traced a string to the logger (with the loglevel LL_TRACE)
• beginProfile($token)/endProfile($token): marks the beginning or the end of profiling
• addLogRoute($route): adds a route to the logger.
• getLogLines(): returns the full log.
• processLog(): processes the log with a defined log route.
• useExceptionHandler(): sets the ExceptionHandler.
• processException($exception): handles an exception.

The use of logging in source code is very simple. At the beginning, the logger is set with the desired logging output and the exception handler

LimbasLogger::addLogRoute(new LimbasWebLogRoute());
LimbasLogger::useExceptionHandler();

Then beginProfile() and endProfile() define the area for which a log log is to be created. Finally, echo LimbasLogger::processLog(); triggered the log output.

<?php
$criteria = array();
$lrJob = LimbasRecord::model('bck_jobs', array('ID', 'ENABLED', 'NAME', 'TYPE', 'LEVEL', 'POOL', 'FILESET', 'SCHEDULE', 'JOBDEF', 'CLIENT', 'PRIORITY'));
$jobs = $lrJob->findAll($criteria);
foreach($jobs as $job)
{
 echo 'Job {'."\n";
 echo ' Name = '.$job->__get('NAME')."\n";
 echo ' Enabled = '.(($job->__get('ENABLED')) ? 'yes' : 'no')."\n";
 echo ' JobDefs = '.$job->__get('JOBDEF')."\n";
 echo ' Type = '.$job->__get('TYPE')."\n";
 echo ' Client = '.$job->client[0]."\n";
 echo ' FileSet = '.$job->fileset[0]."\n";
 echo ' Pool = '.$job->pool[0]."\n";
 echo ' Level = '.$job->__get('LEVEL')."\n";
 echo ' Schedule = '.$job->__get('SCHEDULE')."\n";
 echo ' Write Bootstrap = /var/lib/bacula/Client-'.$job->client[0].'.bsr'."\n";
 echo ' Priority = '.$job->__get('PRIORITY')."\n";
 echo '}'."\n\n";
}
?>