Difference between revisions of "LmbObject API/en"

From Limbas Wiki

Jump to: navigation, search
(Die Seite wurde neu angelegt: „LmbObject API“)
 
(Die Seite wurde neu angelegt: „The logging functionality is composed of different classes. First, there is the interface LimbasLogRoute. This is implemented by the classes LimbasFileLogRoute…“)
(49 intermediate revisions by the same user not shown)
Line 1: Line 1:
<-- zurück zu '''[[DOCLimbasAdmin|Admin-Dokumentation]]''' / <-- zurück zur '''[[Hauptseite|Hauptseite]]'''
+
<-- back to '''[[DOCLimbasAdmin|Admin-Dokumentation]]''' / <-- back to '''[[Hauptseite/en|Main Page]]'''
----
+
____
  
=Was bietet die neue API - ein Überblick=
+
=What does the new API offer? - an Overview=
  
Die neue API bietet Ihnen die Möglichkeit eine Datenbanktabelle als Objekt zurückzugeben und auf diesem Objekt verschiedene Methoden auszuführen. Möchten Sie zum Beispiel ein Objekt Kunde mit den Attributen ID, Name und Namenszusatz, erhalten Sie dieses durch den folgenden Aufruf:
+
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'));
 
  $lrKunde = LimbasRecord::model('KUNDEN', array('ID', 'NAME', 'NAME_ZUSATZ'));
  
Allgemein lautet der Aufruf:
+
In general, the call is:
  
 
  $object = LimbasRecord::model($tableName, $attributes=null);
 
  $object = LimbasRecord::model($tableName, $attributes=null);
  
Zurückgegeben wird eine statische Instanz der genannten LimbasRecord Klasse, im Beispiel Kunden, an der anschließend die Klassenmethoden aufgerufen werden können.
+
It returns a static instance of the named LimbasRecord class, in the example Customers, where the class methods can be called afterwards.
  
An einer solchen Objektinstanz können nun nicht nur Methoden ausgeführt werden, sondern auch mit diesem Objekt verknüpfte Objekte zurückgegeben werden oder von diesem Objekt neue Objekte abgeleitet werden.
+
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.
  
Möchten Sie beispielsweise die Kontakte zu einem Kunden, holen Sie sich zuerst das Objekt Kunden, mit den Attributen ID und Kontakte. Im nächsten Schritt holen Sie sich mit Hilfe der Funktion findById() den gewünschten Kunden und an diesem anschließend die Kontakte.
+
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.
  
  $lrKunde = LimbasRecord::model('KUNDEN', array('ID', 'Kontakte'));
+
  $lrCustomer = LimbasRecord::model('CUSTOMERS', array('ID', 'Contacts'));
  $kunde = $lrKunde->findById(1);
+
  $customer = $lrCustomer->findById(1);
  $relation = $kunde->KONTAKTE();
+
  $relation = $customer->CONTACTS();
  
Ein weiterer Teil der neuen API ist die Möglichkeit sich Logging-Protokolle erstellen zu lassen. Dabei haben Sie die Wahl sich die Ausgaben als einfache Logging Strings zurückgeben zu lassen, die Logging Strings in eine Datei ausgeben zu lassen oder als Webausgabe aufbereiten zu lassen.
+
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.
  
Auch Darstellung der echo Ausgabe wurde für Objekte erweitert.
+
Also representation of the echo output was extended for objects.
  
=Quellen zur API=
+
=Sources to the API=
  
Den Source Code der API finden Sie im Verzeichnis limbas_src → extra → lmbObject. Er ist in drei Packages eingeteilt:
+
The source code of the API can be found in the directory limbas_src → extra → lmbObject. It is divided into three packages:
  
* base: enthält die abstrakte Klasse LimbasComponent, in der einige der magischen Methoden behandelt werden, sowie die Klasse LimbasException.
+
* base: contains the abstract class LimbasComponent, which deals with some of the magic methods, and the class LimbasException.
  
* db: enthält die Klassen LimbasRecord und LimbasRelation, die beide von der Klasse LimbasComponent erben und die Klasse LimbasRecordException die von der Klasse LimbasException erbt. Bei der Klasse LimbasRecord handelt es sich um die Schnittstelle zur Datenbank, die Klasse LimbasRelation stellt die Verknüpfung zwischen zwei Datenbanktabellen dar.
+
* 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: enthält das Interface LimbasLogRoute , die Klassen LimbasPlainLogRoute, LimbasWebLogRoute und LimbasFileLogRoute, die das Interface LimbasLogRoute implementieren und die Logeinträge entweder „unbehandelt“ ausgeben, für das Web aufbereiten oder in eine Datei speichern und die Klasse LimbasLogger in der die einzelnen Loggingeinträge gesammelt werden.
+
* 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=
 
=LimbasRecord=
  
==Beschreibung der wichtigsten Methoden der Klasse LimbasRecord==
+
==Description of the main methods of the class LimbasRecord==
  
Im Folgenden werden die wichtigsten Methoden der Klasse LimbasRecord beschrieben die für die Verwendung in einer Erweiterung möglich sind.
+
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)
 
  public static function model($tableName, $attributes=null)
  
Die zentrale Methode der Klasse ist public static function model($tableName, $attributes=null). Sie gibt ein statisches Modell der genannten Limbas Klasse zurück. An dieser statischen Klasseninstanz können anschließend die Klassenmethoden aufgerufen werden. Als Parameter werden der Tabellenname und die zu verwendenden Attribute benötigt.
+
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)
 
  public function findAll($criteria)
  
Mit der Funktion findAll($criteria)können an der ermittelten Klasseninstanz alle Datensätze, die den mitgegebenen Kriterien entsprechen, abgefragt werden. Sehen Sie sich dazu folgendes Beispiel an:
+
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'));
 
  $lrKunde = LimbasRecord::model('KUNDEN', array('ID', 'NAME', 'NAME_ZUSATZ'));
Line 59: Line 59:
 
  echo '</div>';
 
  echo '</div>';
  
Zuerst wird mit „model“ das Objekt „Kunden“ geholt. In der nächsten Zeile werden die Kriterien für die Funktion findAll definiert. Sie besagen, dass maximal drei Datensätze, der Seite 18 ausgegeben werden, aufsteigend nach dem Namen sortiert. Anschließend wird die Funktion findAll am Objekt $lrKunde ausgeführt und die Datensätze an $kunden zurückgegeben. Zum Abschluss werden die geholten Datensätze in einer for-Schleife durchlaufen und mit echo ausgegeben. Dabei wird intern die magische Methode __toString aufgerufen.
+
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.
  
 
http://limbas.com/images/wiki/de/admin/tools_erweiterungen/EchoKunden.png<br>
 
http://limbas.com/images/wiki/de/admin/tools_erweiterungen/EchoKunden.png<br>
Line 65: Line 65:
 
  public function findById($id)
 
  public function findById($id)
  
Entsprechend funktioniert auch die Funktion findById($id). Hier wird anstatt allen Datensätzen der Datensatz mit der mitgegebenen Id zurückgegeben.
+
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)
 
  public function save($runValidation=false, $attributes=null)
  
Die Funktion save speichert das Objekt an dem die Funktion aufgerufen wird. Dabei wird bei einem neuen Objekt intern die Funktion insert() aufgerufen, bei einem bereits bestehenden update(). Als Parameter wird übergeben, ob eine Validierung stattfinden soll und welche Attribute gespeichert werden sollen, wobei beide Parameter optional sind. Der Rückgabewert der Funktion ist true, wenn das Speichern erfolgreich war und false wenn nicht.
+
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)
 
  public function saveRelation($field, $other)
  
Ebenso wie das Objekt kann selbstverständlich auch die Beziehung von einem Objekt zum anderen gespeichert werden. Als Parameter wird dabei der Feldname des zu verknüpfenden Feldes und das zu verknüpfende Objekt übergeben. Der Rückgabewert der Funktion ist true, wenn das Speichern erfolgreich war und false wenn nicht.
+
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()
 
  public function delete()
  
Ein Objekt kann natürlich nicht nur gespeichert werden, sondern auch gelöscht. Hierzu gibt es die Funktion delete(), die einfach an dem zu löschenden Objekt aufgerufen wird.
+
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-Methoden der Klasse LimbasRecord==
+
==getter-/setter-methods of the class LimbasRecord==
  
In der Objektorientierung erfolgt der Zugriff auf die einzelnen Attribute in der Regel über getter und setter Methoden. Auch in der Klasse LimbasRecord gibt es zahlreiche getter- und setter- Methoden um auf die Attribute zugreifen zu können. Beispielhaft sei hier die Funktion zur Rückgabe der „Attributes“ gezeigt.
+
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() {
 
  public function getAttributes() {
Line 87: Line 87:
 
  }
 
  }
  
Mit Ausnahme der Funktion getDefinition($name) haben die getter-Funktionen keine Parameter die übergeben werden und sind immer entsprechend der gezeigten Funktion aufgebaut. Es gibt folgende weitere getter-Funktionen:
+
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()
 
* getAttributeIds()
Line 98: Line 98:
 
* getFindMetaData().
 
* getFindMetaData().
  
Auch die setter-Funktionen sind einfache Funktionen wie folgendes Beispiel zeigt:
+
The setter functions are simple functions, too, like the following example shows:
  
 
  public function setAttributes($attributes) {
 
  public function setAttributes($attributes) {
Line 104: Line 104:
 
  }
 
  }
  
Es gibt folgende weitere setter-Funktionen:
+
There are the following additional setter functions:
  
 
* setAttributes($attributes)
 
* setAttributes($attributes)
Line 111: Line 111:
 
* setLoading($loading).
 
* setLoading($loading).
  
==Zustandsabfragen der Klasse LimbasRecord==
+
==State queries of class LimbasRecord==
  
Ein weiterer Bestandteil der Klasse LimbasRecord sind verschiedene Zustandsabfragen, die im positiven Fall true zurückgeben, ansonsten false. Dabei kann beispielsweise überprüft werden ob es ein Attribut mit dem übergebenen Namen gibt „isAttribute($name)“ oder ob sich der Datensatz geändert hat „isChanged(). Weitere Zustandsabfragen sind:
+
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),
 
* isUsableAttribute($name),
Line 120: Line 120:
 
* isNew().
 
* isNew().
  
==Transaktionshandling==
+
==Transaction Handling==
  
Über die Funktionen startTransaction(), endTransaction() und rollbackTransaction() kann auf einfache Weise eine Datenbankaktion in einer Transaktion ausgeführt werden. Soll beispielsweise das Speichern eines neuen Kontaktes in einer Transaktion ablaufen sieht das wie folgt aus:
+
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 = new LimbasRecord('kontakte');
Line 131: Line 131:
 
  LimbasRecord::endTransaction();
 
  LimbasRecord::endTransaction();
  
Die Transaktion wird mit startTransaction() gestartet und braucht bei Beendigung zwingend den Aufruf endTransaction().
+
The transaction is started with startTransaction() and needs the call endTransaction() on completion.
  
 
=LimbasRelation=
 
=LimbasRelation=
  
==Welche Methoden gibt es für das verknüpfte Objekt==
+
==What methods are available for the linked object?==
  
Die Klasse LimbasRelation stellt die Verknüpfung von zwei Datenbankobjekten dar und beinhaltet die Funktionen um an dieser Verknüpfung Veränderungen vorzunehmen. Im Folgenden werden, wie für die Klasse LimbasRecord, die für die Verwendung in einer Erweiterung wichtigsten dieser Funktionen näher betrachtet.
+
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.
  
Die Klasse LimbasRelation enthält bis auf zwei Ausnahmen nur getter- und setter- Funktionen und Abfragen, die überprüfen, ob ein bestimmtes Attribut oder Objekt vorhanden ist. Bei den beiden anderen Funktionen handelt es sich um die Funktionen addCriteria($name, $value), die einen „criteria Ausdruck“ hinzufügt und addObject($object) . Wie der Name schon sagt fügt addObject($object) ein Objekt hinzu, um genau zu sein ein verknüpftes Objekt. In der Funktion wird dabei zuerst ein Logging-Eintrag erstellt. Nach einer Überprüfung, ob es sich um ein Objekt der richtigen Datenbanktabelle handelt wird es im positiven Fall zu der Liste der verknüpften Objekte hinzugefügt. Im negativen Fall wird eine LimbasRecordException geworfen.
+
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- Funktionen==
+
==getter-/setter- Functions==
  
Die getter Funktionen haben auch hier alle den gleichen Aufbau.
+
The getter functions all have the same structure here as well.
  
 
  public function getObjects() {
 
  public function getObjects() {
Line 150: Line 150:
 
  }
 
  }
  
Im ersten Schritt wird eine log-Nachricht geschrieben, im zweiten wird ein Array der entsprechenden Objekte zurückgegeben. Außer der im Beispiel zu sehenden getObjects() gibt es noch die Funktionen
+
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()
 
* getStrings()
Line 156: Line 156:
 
* getAttributes().
 
* getAttributes().
  
Auch die setter-Funktionen sehen im Wesentlichen alle gleich aus. Zuerst wird eine log-Nachricht geschrieben, anschließend werden die Objekte ersetzt.
+
The setter functions also essentially all look the same. First, a log message is written, then the objects are replaced.
  
 
  public function setCriteria($criteria) {
 
  public function setCriteria($criteria) {
Line 163: Line 163:
 
  }
 
  }
  
Es unterscheidet sich lediglich die Funktion setObject($objects) leicht von diesem Schema.
+
Only the function setObject($objects) differs slightly from this scheme.
  
 
  public function setObjects($objects) {
 
  public function setObjects($objects) {
Line 173: Line 173:
 
  }
 
  }
  
Hier werden die übergebenen Objekte in einer Schleife durchlaufen und für jedes der Objekte wird die Funktion addObject($object) ausgeführt.
+
Here the passed objects are looped through and for each of the objects the function addObject($object) is executed.
  
Zuletzt gibt es noch die beiden Funktionen hasObjects() und hasStrings(), die jeweils überprüfen, ob es Objekte bzw. Strings gibt und im positiven Fall true zurückgeben, ansonsten false.
+
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=
 
=Magic Methods=
  
In objektorientiertem PHP gibt es sogenannte „magic methods“. Diese magischen Methoden werden bei bestimmten Aktionen automatisch von PHP aufgerufen. Sie beginnen immer mit einem doppelten Unterstrich, weshalb diese Notation nicht für andere Funktionen verwendet werden sollte. In PHP gibt es folgende magische Methoden:
+
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()
 
* __construct()
Line 197: Line 197:
 
* __autoload()
 
* __autoload()
  
Zur näheren Erläuterung magischer Funktionen betrachten wir die Methode __construct(). Jede Klasse besitzt diese automatisch, sie kann aber auch mit einer neuen Funktionsweise überschrieben werden. Das folgende Beispiel zeigt die __construct() Methode der Klasse LimbasRecord. Als Parameter hat sie einen Tabellennamen von Limbas und zu verwendende Attribute. In der Methode wird zuerst die __construct() Methode der vererbenden Klasse aufgerufen, anschließend wird der Tabellennamen in Großschreibung geändert, ein Logeintrag gespeichert und die Methode createAttributes aufgerufen.
+
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) {
 
  public function __construct($table, $attributes=null) {
Line 206: Line 206:
 
  }
 
  }
  
Möchte man zum Beispiel einen neuen Kunden erstellen und ruft $kunde = new LimbasRecord('kunden'); auf wird automatisch der beschriebene Konstruktor __construct() aufgerufen und die neue Klasse erstellt.
+
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.
  
=Wie funktioniert das Logging ?=
+
=How does Logging work?=
  
Die Logging Funktionalität baut sich aus verschiedenen Klassen zusammen. Zunächst gibt es das Interface LimbasLogRoute. Dieses wird von den Klassen LimbasFileLogRoute, LimbasPlainLogRoute und LimbasWebLogRoute implementiert. In diesen Klassen werden die Log-Nachrichten für die entsprechenden Ausgabewege, d.h. Dateiausgabe, einfache Ausgabe und Webausgabe aufbereitet. Die Klasse LimbasLogger übernimmt die eigentliche Arbeit der Nachrichtensammlung und stellt dazu verschiedene Funktionen zur Verfügung:
+
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): Loggt einen String zum Logger (mit dem Loglevel LL_INFO)
 
* log($str,$level=self::LL_INFO): Loggt einen String zum Logger (mit dem Loglevel LL_INFO)

Revision as of 13:26, 7 June 2019

<-- back to Admin-Dokumentation / <-- back to Main Page ____

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 to 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.

http://limbas.com/images/wiki/de/admin/tools_erweiterungen/EchoKunden.png

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): Loggt einen String zum Logger (mit dem Loglevel LL_INFO)
  • trace($str): Traced einen String zum Logger (mit dem Loglevel LL_TRACE)
  • beginProfile($token)/endProfile($token): markiert den Beginn bzw. das Ende des Profiling
  • addLogRoute($route): fügt dem Logger eine Route hinzu.
  • getLogLines(): gibt den vollständigen Log zurück.
  • processLog(): verarbeitet den Log mit einer definierten Log-Route.
  • useExceptionHandler(): setzt den ExceptionHandler.
  • processException($exception): verarbeitet eine Exception.

Die Verwendung des Logging im Source Code ist denkbar einfach. Zu Beginn wird der Logger mit der gewünschten Logging-Ausgabe und der Exception Handler gesetzt.

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

Mit beginProfile() und endProfile() wird anschließend der Bereich definiert für den ein Log-Protokoll erstellt werden soll. Abschließend wird mit echo LimbasLogger::processLog(); die Log-Ausgabe angestoßen.

Beispielhafte Verwendung von lmbObject

In einem Beispiel aus der Praxis soll gezeigt werden, wie einfach der Datenzugriff mit lmbObject erfolgen kann. Es handelt sich um folgende Aufgabenstellung: für das Backup Programm Bacula sollen die Konfigurationseinträge für die Elemente Clients, Pools, FileSets und Jobs generiert werden. Die Vorgehensweise für die einzelnen Elemente ist immer gleich, weshalb hier beispielhaft die „jobs“ behandelt werden, die Sie sich im folgenden Source Code genauer anschauen können.

<?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";
}
?>

Zunächst wird die statische Instanz $lrJob der Klasse LimbasRecord mit den benötigten Attributen für die Datenbanktabelle bck_jobs erstellt. An diesem Objekt kann anschließend die Funktion findAll($criteria) aufgerufen werden, die alle Datensätze für die mitgegebenen Kriterien findet. Die gefundenen Jobs werden anschließend in einer Schleife foreach($jobs as $job) durchlaufen, um mit echo die Ausgabe für die Konfigurationseinträge zu erzeugen. Dabei wird über die Variable $job auf die benötigen Attribute zugegriffen (z.B. $job->__get('NAME') od. $job->client[0]).