Plugin eCMS-API

Mit dem API-Plugin können Funktionen und Daten einer eCMS-Installation für externe Zugriffe freigeschaltet und konfiguriert werden.

Short Facts

Über das API-Plugin können HTTP-Schnittstellen für Fernzugriffe (RPCs) auf sämtliche eCMS- und Plugin-Funktionen von anderen Servern oder Computern konfiguriert und gesichert werden.

ACHTUNG: Dieses Plugin sollte von technisch versierten Personen, im Zweifelsfalle mit (PHP-) Programmierkenntnissen, verwendet und konfiguriert werden. Unachtsame Handhabung öffnet ansonsten ggfs. die eCMS-Installation nach außen und ermöglicht es eventuell Angreifern an interne Daten zu gelangen oder die Installation zu kompromittieren!

Um das eCMS-System trotz allem möglichst sicher und komfortabel von außen ansprechbar und konfigurierbar zu machen, bringt das API-Plugin schon eine Menge guter Dinge mit:

  • Mehrere parallele, eigene APIs können definiert werden.
  • Pro API können beliebig viele Ressourcen, d.h. PHP-Klassen-Methoden-Aufrufe freigeschaltet werden.
  • Für jede Ressource kann der Zugriff für eCMS-User freigeschaltet werden.
  • Zugriffsschutz auf IP-Basis und User-Token-Authentication.
  • Zeitliche Zugriffssteuerungen.
  • Unterstützt HTTP und HTTPS (SSL) Protokoll.
  • Zugriff auf Standard-eCMS-PHP-Klassen.
  • Zugriff auf andere (eigene) Plugins konfigurierbar.

Installation

Die Installation lässt sich einfach über das Backend des eCMS über die Plugin-Verwaltung durchführen.

Konfiguration

Einführung und Grundlagen

Ganz vereinfacht gesagt, kümmert sich das API-Plugin darum, das eingehende HTTP(S)-Requests auf die entsprechende PHP-Klassen-Methode ge'routed werden und das Ergebnis jeweils im gleichen Request wieder zurückgegeben wird.

Bei einem eingehenden Request läuft folgendes intern ab (Gut-Fall Darstellung, d.h. ohne Fehlerbehandlung):

  1. HTTP - Request wird entgegengenommen.
    Parameter: API-Label, User-Auth-Token, Ressourcen-Label
  2. Request-Parameter werden geprüft, ob in API-Konfiguration vorhanden und freigeschaltet
  3. eCMS-User-Settings und zugehörige App-Rights werden geladen
  4. eCMS-User-Session wird intialisiert
  5. eCMS-Site-Instanz wird geladen
  6. Requestete Ressource, d.h. die zugehörige PHP-Klasse wird instanziiert
  7. Die requestete Ressourcen-Methode der Klasse wird ausgeführt
  8. Das Ergebnis (Result-Array) in Rückgabe-Format gewandelt und als Text im HTTP-Request zurückgeliefert

 

API

In diesem Plugin ist eine "API" die Gruppierung von beliebig vielen Ressourcen (= PHP-Methoden. Siehe unten).

Listen-Ansicht

In der Listenansicht werden alle definierten APIs dargestellt.

Löschen

Über Löschen können ganze APIs inklusive ihrer Ressourcen-Konfiguration und User-Freigaben gelöscht werden. Dieser Löschvorgang kann nicht wieder rückgängig gemacht werden!

Exportieren

Die dargestellten Daten in der Liste können komfortabel exportiert werden. Genauere Informationen dazu gibt es in dem Artikel: Arbeiten mit Listen.

Anlegen und Bearbeiten

Alle Datenfelder zur API-Konfiguration sind hier beschrieben: Daten-Typ "API"

Löschen

APIs können über die API-Liste gelöscht werden.

 

User

"Jemand", der über die API von außen auf das eCMS-System zugreift, muss zuvor als eCMS-User auch über die normale eCMS-User-Verwaltung angelegt worden sein. Erst dann kann dieser User hier weiter für den API-Zugriff freigeschaltet werden.

Warum muss zuvor ein eCMS-User angelegt werden?
Ganz einfach: eCMS-User können je nach Applikation bzw. Plugin, wie bspw. "eCommerce Suite", "eCMS Admin", usw. unterschiedliche Daten- und Funktionsrechte konfiguriert bekommen. Darüber werden zum Beispiel Dinge festgelegt, welche Datenbank-Spalten er überhaupt abfragen darf und welche Aktionen (CREATE, READ, UPDATE, DELETE usw.) er für gewisse Datensätze ausführen darf.
 

Listen-Ansicht

In der Liste werden alle konfigurierten API-User mit ihrem Freischaltungszustand sowie der Anzahl der Ihnen zur Verfügung gestellten Ressourcen dargestellt.

Sammel Aktionen
Ressourcen-Freigabe kopieren

Hiermit können bereits konfigurierte User-Ressourcen-Freigaben auf einen oder mehreren ausgewählten User kopiert werden.

Löschen

User können, inklusive ihrer Ressourcen-Freigaben hierüber gelöscht werden. Das Löschen kann nicht rückgängig gemacht werden!

Exportieren

Die dargestellten Daten in der Liste können komfortabel exportiert werden. Genauere Informationen dazu gibt es in dem Artikel: Arbeiten mit Listen.

Anlegen und Bearbeiten

Alle Datenfelder zum API-User sind hier beschrieben: Daten-Typ "API User"

Löschen

Über die User-Liste können einzelne User-Konfigurationen gelöscht werden.

Ressourcen

Ressourcen die eigentlichen internen Funktionen, die über die API nach "außen" freigeschaltet werden und eben von extern aufgerufen werden können (RPC: remote procedure calls).

Jede PHP-Klassen-Methode, die von außen aufgerufen werden soll, muss zunächst hier konfiguriert werden. Dann erst kann sie einer API zugordnet und für API-User freigeschaltet werden.
Das mag im ersten Augenblick recht umständlich erscheinen, ermöglicht aber einen fein granularisierbaren und vor allem sicheren Betrieb, der vor zu großer, unbeabsichtigter "Offenheit" bewahren soll.

Das Ergebnis der aufgerufenen PHP-Klassen-Methode muss ein Result-Array mit einem Boolean "status" Array-Key sein ("$RESULT[status] = true || false;"). Empfohlen wird für Rückgabedaten den Array-Key "data" im Result-Array zu verwenden ("$RESULT[data] = Array || String || Integer || etc.;"). Für die Rückgabe von Meldungen (z.B. Fehler, Info, etc.) wird der Array-Key "msg" im Result-Array empfohlen ("$RESULT[msg] = Array;").  

Die Parameter der PHP-Klassen-Methode sollten in einem Parameter-Array zusammengefasst sein. Dies vereinfacht die Ressourcen-Konfiguration und die Übergabe von Parametern beim Aufruf. 

Listen-Ansicht

In der Liste werden alle Ressourcen von allen API-Konfigurationen angezeigt.

Um nur von einer API die freigeschalteten Ressourcen zu sehen, müssen Sie diese in der Liste über die Spalte "API-Label" entsprechend filtern.

User für Ressource aktivieren/deaktivieren

Über diesen Dialog können User für API Ressourcen frei geschaltet ("enabled") werden oder der Ressourcen Zugriff vorübergehend entzogen ("disabled") werden. 

User von Ressource löschen

Über diesen Dialog können User-Freigaben für Ressourcen gelöscht werden. 

Exportieren

Die dargestellten Daten in der Liste können komfortabel exportiert werden. Genauere Informationen dazu gibt es in dem Artikel: Arbeiten mit Listen.

Anlegen und Bearbeiten

Alle Datenfelder zur API-Konfiguration sind hier beschrieben: Daten-Typ "API Ressource"

Löschen

Ressourcen-Konfigurationen können über die Ressourcen-Liste wieder gelöscht werden.

Externe API-Aufrufe

Voraussetzungen

Damit das eCMS überhaupt einen Request von außen entgegenehmen und erfolgreich beantworten kann, müssen folgende Grundvoraussetzungen gegeben sein:

  • API-Plugin muss installiert sein
  • Wenigstens eine "API" muss angelegt sein
  • Wenigstens eine "Ressource" muss konfiguriert sein und dieser "API" zugewiesen sein. Außerdem muss diese Ressource für einen API-User freigeschaltet sein.
  • Wenigstens ein eCMS-User muss angelegt sein und Zugriff auf die Site haben. Des Weiteren muss ein "API-User" zusätzlich angelegt und mit dem eCMS-User verknüpft sein.

URL & Syntax

Nachfolgend einige Short-Facts zum API Aufruf

  • Die API-Parameter können als GET und/oder POST Daten übergeben werden. Werden beide Input-Daten übergeben, werden die Daten zusammengeführt, wobei die POST Daten die höhere Priorität haben.
  • Neben den Status-Informationen im HTTP-Body, gibt auch der Status-Code im HTTP-Header Auskunft über den Erfolg und Misserfolg des API-Aufrufs
  • Bei Authentication-Fehlern sind die Informationen in der Aufruf-Antwort aus Sicherheitsgründen sehr gering. Genauere Informationen finden Sie im eCMS Site-Log.
  • Es können nur Ressourcen (PHP-Methoden) aufgerufen bzw. vorab als Ressource konfiguriert werden, die ein Argument (Array) als Aufruf-Parameter haben und immer ein Result-Array in Standard-Struktur zurückliefern.
  • Alle Eingabe-Daten sowie Ergebnisse sind im Normalfall im UTF-8 Zeichensatz kodiert.

Der API Aufruf erfolgt über das " api.php" Script im " bin" Verzeichnis der eCMS Installation. Die URL, hier ohne weitere Parameter dargestellt, ist daher wie folgt:

  1. http://<your eCMS-Installation-URL>/bin/api.php

Parameter

Folgenden die Parameter, die in den HTTP-GET oder -POST Daten übergeben werden müssen.

Achten Sie darauf, dass diese ggfs. sauber URL-encoded sind. Grundsätzlich ist alles im UTF-8 Zeichensatz zu encoden.

Parameter Typ Beschreibung
api_label Text (Pflicht)  Das Label der API, zur der die aufgerufene Ressource gehört.
user_token Text (Pflicht)  Zugriffs-Token des API Users.
resource Text (Pflicht)  Das Label der API Ressource die aufgerufen werden soll.
params Array (Optional)  Parameter der Ressource. 

 

Ergebnisse

HTTP-Results

Ob, die API korrekt angesprochen (und korrekt konfiguriert) wurde, läßt sich am ehesten an den HTTP-Antwort-Codes ablesen. Diese folgen in ihrer Bedeutung dem Standard.

HTTP-Result-Code Beschreibung
200

Aufruf OK!
Authorisierung OK, Methode/Ressource konnte ausgeführt werden. Alle Methoden-Results sind im zurückgelierferten Result-Content enthalten und sollten evaluiert werden.
 

Achtung: Auch wenn hier ein 200-OK zurückkommt, kann es sein, dass bspw. die Ressource selbst noch einen Fehler zurückliefert (z.B. "User konnte nicht angelegt werden, weil er bereits existiert!"). Das muss aus selbst aus dem Result-Content heraus extrahiert werden. Das 200-OK bedeutet somit lediglich, dass der API-Aufruf an sich OK war!

403

Authentication ERROR!

Zugriff nicht erlaubt, weil irgendeine User/API/Ressourcen-Konfiguration dafür nicht vorhanden oder nicht freigeschaltet ist. Nach außen werden aus Sicherheitsgründen keine weiteren Infos zurückgegeben. Die Details eines solchen fehlgeschlagenen Aufrufs stehen im internen eCMS-Site-Log.

404

Not Found ERROR

Wenn eine requestete Ressource, API-Label oder zu streamende Datei nicht gefunden werden konnte, wird ein 404 zurückgegeben.

500

Internal Server ERROR

Wenn eine requestete Ressource und API konfiguriert, d.h. in dem API-Plugin gefunden werden konnte, diese aber nicht ausgeführt werden konnte, weil bspw. die PHP-Klasse doch nicht auf dem Server vorhanden ist oder anderweitige interne Probleme gegeben hat, wird ein 500 zurückgeliefert.

 

Result-Content

Im Normalfall, vor allem wenn 200-OK HTTP-Result zurückgegeben wurde, sollte ein JSON-encodetes Result-Array zurückgeliefert werden mit folgender Struktur.

Dies ist das DIREKTE returned Result aus der PHP-Methode, die aufgerufen wurde! Die Methoden, naja, die Entwickler der Methoden... :), sollen sich daran halten absolut konforme Result-Arrays zurückzuliefern. Es kann also theoretisch sein, dass hier auch ein anderes Ergebnis vom anderen Daten-Typ und -Struktur zurückkommen könnte.

  1. {
  2.     "status": true,
  3.  
  4.     "data": {
  5.         "var_a": 123,
  6.         "var_b": "hello world"
  7.         },
  8.  
  9.     "msg" : null
  10. }

 

Array-Key Type Beschreibung
status boolean (normaly) TRUE, wenn Methode selbst erfolgreiche Ausführung signalisiert. Ansonsten FALSE.
msg Array (optional) Message-Array, mit Error-Codes und Error-Strings.
data Array (optional) "Free"-Data-Array, mit Methoden-spezifischen-Ergebnis-Daten.

Beispiel - Einfacher Call

Sie können die API im Browser testen. Nachfolgend ein Beispiel-Aufruf mit GET Daten:

  1. http://www.example.com/bin/api.php?api_label=my_api&user_token=my_api_token&resource=my_api_method&params[fields][var_a]=123&params[fields][var_b]=hello+world&params[filter][id]=1

Das Ergebnis des API Aufrufs ist ein JSON String. Nachfolgend ein Beispiel-Ergebnis, welches Result-Content zurückgeliefert wird:

  1. {"status":true,"data":{"var_a":123,"var_b":"hello world"},"msg":null}

Beispiel - API Client (PHP)

Folgend ein PHP-Snippet, welches als einfache Basis für einen eigenen PHP-Client zum Aufrufen der eCMS-API verwendet werden kann.

In PHP verwenden Sie am besten die CURL Methoden um einen API Aufruf zu senden. 

Nachfolgend ein Beispiel-Aufruf mit POST Daten:

  1. // Request parameter
  2. $data = array(
  3. 'api_label' => 'my_api',
  4. 'user_token' => 'my_api_token',
  5. 'resource' => 'my_api_method',
  6. 'params' => array('fields' => array('var_a' => 123, 'var_b' => 'hello world'), 'filter' => array('id' => 1)),
  7. );
  8.  
  9. // Create CURL instance
  10. $c = curl_init('http://www.example.com/bin/api.php');
  11.  
  12. // Set POST data
  13. curl_setopt($c, CURLOPT_POST, 1);
  14. curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($data));
  15.  
  16. // Enable return of response body
  17. curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
  18.  
  19. // Send request to eCMS-API:
  20. $src = curl_exec($c);
  21.  
  22. if (intval(curl_errno($c)) > 0){
  23.  
  24.     // Error in CURL Request
  25.  
  26. } elseif (strlen($src)==0 || is_array($res = json_decode($src, true))==false || array_key_exists('status', $res)==false){
  27.  
  28.     // Response-Structure invalid
  29.  
  30. } else {
  31.  
  32.     // Response OK
  33.     // ...evaluate the Result-Array:  $res
  34. }

 

Freigebbare Resourcen (PHP)

Es können nur Methoden von PHP-Klassen über die API nach außen freigegeben werden, die einigen grundsätzlichen Voraussetzungen genügen.

 

PHP-Methoden-Voraussetzungen

Grundanforderungen an eine Methode sind:

  • Erstes Aufruf-Argument ist vom Typ ARRAY. Dies kann optional sein.
  • Weitere Aufruf-Argumente dürfen vorhanden sein, müssen dann aber optional sein.
  • Der Return-Typ ist immer ARRAY.

 

Beispiel mit minimal erfüllten Voraussetzungen:

  1. class myClass4API
  2. {
  3.     public function mySimpleFunc ($Params)
  4.     {
  5.         // ... my actual code here.
  6.     
  7.  
  8.         // Setup our Result-Array to be returned:
  9.         $Result['status'] = TRUE; 
  10.     
  11.         return $Result;
  12.     }
  13. }

 

Das Return-​Array

Array-Key Typ Beschreibung
[status] boolean
(Pflicht)

TRUE: Wenn die Methode erfolgreich ihre Aufgabe erledigen konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text] string
(Optional)

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

  • "ERROR" - Schwerer Ausführungsfehler.
  • "WARNING" - Warnung bei Ausführung.
  • "INFO" - Zusätzliche (Debug) Meldungen.
  • "OK" - Ausführung OK.

 

Beispiel Result

  1. $R['status'] = FALSE;
  2.  
  3. $R['msg'][0]['type'] = 'ERROR';
  4. $R['msg'][0]['text'] = 'ERROR: Something went wrong. Actually this is the reason: ...foo! foo!';
  5.  
  6. $R['msg'][1]['type'] = 'OK';
  7. $R['msg'][1]['text'] = 'Creating the record XYZ was succesful!';
  8.  

 

 

Typische Methoden & Parameter

Folgend sind einige sehr häufig vorkommende Parameter für verschiedenste, bereits existierende Methoden generell erläutert. Für die konkrete bzw. weiterführende Parameter-Defintion bitte bei der jeweiligen Funktion nachschlagen.

Achten Sie auch darauf, dass die hier genannten Array-Parameter-Keys auch in der API-Ressourcen-Konfiguration freigeschaltet, d.h. ge-"whitelisted" sind!

 

Methoden: ..._get(...)

Liest einen Record.

Parameter

$Params Pflicht Beschreibung Beispiel
[fields] optional

String/Array (faster). Liste der Fields, die returned werden sollen. Wird nichts angegeben wird "*" angenommen, d.h. alle im Model hinterlegten Felder.

Es sollten nur die Felder angegeben werden, die auch wirklich benötigt werden. Speziell bei Multi-Table-Models werden dann auch nur die Tables im SELECT dazu geJOINed, die benötigt werden.

Als String: "firstname,lastname,birthday".

Als Array:
  [0] = "firstname"
 [1] = "lastname"
 [2] = "birthday"

[filter][<field>] optional

String. Pro Field kann hier ein Wert angegeben werden, der dann im WHERE-Statement aufgenommen wird. Im Falle eines virtuellen Fields, wird das in "drvd_select" hinterlegte SQL in das WHERE-Statement mit aufgenommen.

Es wird immer mit "<field> = '<auto-escaped Value>' " gesucht. Mehrere Filter-Felder werden mit AND verknüpft. Die übergebenen Werte werden automatisch escaped (Schutz vor SQL-Injection).

Ist ein Wert null, so wird mit "...<field> IS NULL" im WHERE gesucht.

Hiermit können einfache, SQL-Injection-sichere Filterkriterien realisiert werden. Für komplexere WHERE-Statements bitte [xwhere] benutzen!

MySQL-wildcard-Filter "%" können hier aktuell leider nicht verwendet werden, da auch bei Text-Feldern mit "=" geprüft wird und nicht mit SQL LIKE.

['lastname'] ="e-matters"
[filter][<field>][search] optional String. Pro Field kann hier ein Suchbegriff angegeben werden, der Field-Typ-spezifisch (INT, FLOAT, TEXT, DATE, DATETIME) interpretiert wird.
Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.

Text: "my_* || ecms_* || *.class.*"
Integer: ">10; <100"
Float: Integer: ">0.5; <=9.999"
Date: "1.12.2012 - 24.12.2012"
DateTime: "> 15.12.2012 12:00"
 

 

Das Return-​Array

Array-Key Typ Beschreibung
[status] boolean

TRUE: Wenn die Datenabfrage durchgeführt werden konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text] string

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

  • "ERROR" - Schwerer Ausführungsfehler.
  • "WARNING" - Warnung bei Ausführung.
  • "INFO" - Zusätzliche (Debug) Meldungen.
  • "OK" - Ausführung OK.
[data][<fields>] mixed

Die eigentlichen Daten des angeforderten Datensatzes in einem assoziativen Array.

 

Methoden: ..._getList(...)

Liest eine Liste von Records.

Parameter

$Params Pflicht Beschreibung Beispiel
[fields] optional

String/Array (faster). Liste der Fields, die returned werden sollen. Wird nichts angegeben wird "*" angenommen, d.h. alle im Model hinterlegten Felder.

Es sollten nur die Felder angegeben werden, die auch wirklich benötigt werden. Speziell bei Multi-Table-Models werden dann auch nur die Tables im SELECT dazu geJOINed, die benötigt werden.

Als String: "firstname,lastname,birthday".

Als Array:
  [0] = "firstname"
 [1] = "lastname"
 [2] = "birthday"

[filter][<field>] optional

mixed. Pro Field kann hier ein Wert angegeben werden, der dann im WHERE-Statement aufgenommen wird. Im Falle eines virtuellen Fields, wird das in "drvd_select" hinterlegte SQL in das WHERE-Statement mit aufgenommen.

Es wird immer mit "<field> = '<auto-escaped Value>' " gesucht. Mehrere Filter-Felder werden mit AND verknüpft. Die übergebenen Werte werden automatisch escaped (Schutz vor SQL-Injection).

Ist ein Wert null, so wird mit "...<field> IS NULL" im WHERE gesucht.

Hiermit können einfache, SQL-Injection-sichere Filterkriterien realisiert werden. Für komplexere WHERE-Statements bitte [xwhere] benutzen!

MySQL-wildcard-Filter "%" können hier aktuell leider nicht verwendet werden, da auch bei Text-Feldern mit "=" geprüft wird und nicht mit SQL LIKE.

['lastname'] ="e-matters"
[filter][<field>][search] optional String. Pro Field kann hier ein Suchbegriff angegeben werden, der Field-Typ-spezifisch (INT, FLOAT, TEXT, DATE, DATETIME) interpretiert wird.
Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.
Text: "my_* || ecms_* || *.class.*"
Integer: ">10; <100"
Float: Integer: ">0.5; <=9.999"
Date: "1.12.2012 - 24.12.2012"
DateTime: "> 15.12.2012 12:00"
 
[filter][<field>][in] optional Array. Pro Field kann hier eine Liste von Begriffen angegeben werden, nach denen als mögliche exakte Werte des entsprechenden Feldes gesucht werden soll.
Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.
['lastname'] = array("e-matters","demo")
[filter][<field>][range] optional Array. Pro Field kann hier ein min-max Bereich angegeben werden, der Field-Typ-spezifisch (INT, FLOAT, TEXT, DATE) interpretiert wird.
Es können hierbei wahlweise "min" und "max" oder auch nur einer der beiden Werte angegeben werden
Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.
Text: array("min" => "A000100","max" => "A000200")
Integer: array("min" => "100","max" => "200")
Float: array("min" => "100,50","max" => "200.30")
Date: array("min" => "24.12.2014","max" => "2014-12-31")
 
[sql][limit][max] optional Integer. Die maxinale Treffer-Anzahl aus der Ergebnis-Menge.

30 - Returned die maximal ersten 30 Zeilen.

100 - Returned die maximal ersten 100 Zeilen

[sql][limit][page] optional Integer. Die aktuelle Ergebnis-Seite aus einer durch "[sql][limit][max]" unterteilten Ergebnis-Menge. Der "page" Parameter beginnt mit "1". Der "[sql][limit][max]" Parameter kann ohne "page" Parameter verwendet werden.

1 - Returned die erste Seite des Abfrage-Ergebnisses.

3 - Returned die dritte Seite des Abfrage-Ergebnisses.

[sql][order] optional

String. Der hier angegebene String, wird ohne weitere inhaltliche Prüfung einfach an das ORDER BY-Statement des SELECTs gehängt.

Achtung: Alle Inhalte müssen sauber zuvor escaped worden sein, um SQL-Injections zu vermeiden!
"firstname DESC"
[sql][group] optional

String. Der hier angegebene String, wird ohne weitere inhaltliche Prüfung einfach an das GROUP BY-Statement des SELECTs gehängt.

Achtung: Alle Inhalte müssen sauber zuvor escaped worden sein, um SQL-Injections zu vermeiden!
"a_id"
[meta][FOUND_ROWS] optional Bool, default FALSE. Wenn TRUE, wird zurückgekliefert wie viele Zeilen das Gesamt-Ergebnis hätte, wenn es nicht durch [sql][limit] begrenzt würde. Wenn allerdings gar kein [sql][limit] gesetzt ist, kann man sich dieses Flag sparen. true
[meta][query] optional Bool, default FALSE. Wenn TRUE, wird die ausgeführte SQL-Query zurückgeliefert. true

 

Das Return-​Array

Array-Key Typ Beschreibung
[status] boolean

TRUE: Wenn die Datenabfrage durchgeführt werden konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text] string

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

  • "ERROR" - Schwerer Ausführungsfehler.
  • "WARNING" - Warnung bei Ausführung.
  • "INFO" - Zusätzliche (Debug) Meldungen.
  • "OK" - Ausführung OK.
[data][<n>][<fields>] mixed

Die eigentlichen Daten als 2-dimensionales Array.

Die erste Array-Ebene ( <n>, von 0 bis N) nummeriert typischerweise die zurückgelieferten Datensätze durch.
In der zweiten Array-Ebene befinden sich jeweils die Daten der angeforderten Datensätze in einem assoziativen Array.

 

Methoden: ..._insert(...)

Fügt einen Record in Datenbank ein.

Parameter

$Params Pflicht Beschreibung Beispiel
[fields] Pflicht

Array. Liste der Felder und ihrer Werte.

Es werden nur die Felder berücksichtigt, die dem Model's "Haupt-Table" zugehörig sind. Alle anderen Felder werden (silently) ignoriert.

Ist ein Wert null, so wird  er auch mit "<field>=NULL" in die Datenbank geschrieben.

  ["firstname"] = "Emil"
 ["lastname"] = "Matters"
 ["birthday"] = "1980-06-30"

 

Das Return-​Array

Array-Key Typ Beschreibung
[status] boolean

TRUE: Wenn das Anlegen erfolgreich durchgeführt werden konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text] string

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

  • "ERROR" - Schwerer Ausführungsfehler.
  • "WARNING" - Warnung bei Ausführung.
  • "INFO" - Zusätzliche (Debug) Meldungen.
  • "OK" - Ausführung OK.
[data][<fields>] mixed

Die eigentlichen Daten des angeforderten Datensatzes in einem assoziativen Array.

 

Methoden: ..._update(...)

Updated einen oder mehrere Records.

Parameter

$Params Pflicht Beschreibung Beispiel
[fields] Pflicht

Array. Liste der Felder und ihrer Werte.

Es werden nur die Felder berücksichtigt, die dem Model's "Haupt-Table" zugehörig sind. Alle anderen Felder werden (silently) ignoriert.

Ist ein Wert null, so wird  er auch mit "<field>=NULL" in die Datenbank geschrieben.

  ["firstname"] = "Emil"
 ["lastname"] = "Matters"
 ["birthday"] = "1980-06-30"

[filter][<field>] optional

mixed. Pro Field kann hier ein Wert angegeben werden, der dann im WHERE-Statement aufgenommen wird. Im Falle eines virtuellen Fields, wird das in "drvd_select" hinterlegte SQL in das WHERE-Statement mit aufgenommen.

Es wird immer mit "<field> = '<auto-escaped Value>' " gesucht. Mehrere Filter-Felder werden mit AND verknüpft. Die übergebenen Werte werden automatisch escaped (Schutz vor SQL-Injection).

Ist ein Wert null, so wird mit "...<field> IS NULL" im WHERE gesucht.

Hiermit können einfache, SQL-Injection-sichere Filterkriterien realisiert werden. Für komplexere WHERE-Statements bitte [xwhere] benutzen!

['a_id'] = "10"

 

Das Return-​Array

Array-Key Typ Beschreibung
[status] boolean

TRUE: Wenn das Update durchgeführt werden konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text] string

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

  • "ERROR" - Schwerer Ausführungsfehler.
  • "WARNING" - Warnung bei Ausführung.
  • "INFO" - Zusätzliche (Debug) Meldungen.
  • "OK" - Ausführung OK.

 

Methoden: ..._delete(...)

Löscht einen oder mehrere Records

Parameter

$Params Pflicht Beschreibung Beispiel
[filter][<field>] optional

mixed. Pro Field kann hier ein Wert angegeben werden, der dann im WHERE-Statement aufgenommen wird. Im Falle eines virtuellen Fields, wird das in "drvd_select" hinterlegte SQL in das WHERE-Statement mit aufgenommen.

Es wird immer mit "<field> = '<auto-escaped Value>' " gesucht. Mehrere Filter-Felder werden mit AND verknüpft. Die übergebenen Werte werden automatisch escaped (Schutz vor SQL-Injection).

Ist ein Wert null, so wird mit "...<field> IS NULL" im WHERE gesucht.

Hiermit können einfache, SQL-Injection-sichere Filterkriterien realisiert werden. Für komplexere WHERE-Statements bitte [xwhere] benutzen!

['a_id'] = "10"

 

Das Return-​Array

Array-Key Typ Beschreibung
[status] boolean

TRUE: Wenn das Löschen durchgeführt werden konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text] string

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

  • "ERROR" - Schwerer Ausführungsfehler.
  • "WARNING" - Warnung bei Ausführung.
  • "INFO" - Zusätzliche (Debug) Meldungen.
  • "OK" - Ausführung OK.