Allgemeine APIs: Inside TYPO3 – Ein Blick in das Innere des CMS
Gerade wenn man noch nicht so tief in TYPO3 eingestiegen ist, wünscht man sich oft eine Art Übersichtsplan über die internen Schnittstellen des Systems. Dieser Artikel soll hier Licht ins Dunkel bringen und die vorhandenen Möglichkeiten in Form der Nutzung verfügbarer Schnittstellen aufzeigen.
Um ein komplexes Software-Projekt wie TYPO3 zu verstehen, muss man als erstes einen Blick in die Vergangenheit wagen. Zunächst hat man als Programmierer eines großen Softwareprojekts freie Hand darüber, welchen Code man wie verwendet und welche Schnittstellen man versucht, zu definieren. Man braucht bestimmte Funktionen und implementiert diese, indem man seine Software um eben diese Bereiche erweitert. Irgendwann aber wird die Software so groß und komplex, dass man selbst als Erfinder nicht mehr alle Klassen und Funktionen überschauen kann.
Um dies zu umgehen, einigt man sich am besten von Anfang an (oder spätestens, wenn neue Funktionalitäten integriert werden) auf so genannte Programmierschnittstellen (engl. API – Application Programming Interface). Diese Schnittstellen stellen häufig benötigte Funktionen zur Verfügung, kapseln aber die Realisierung komplett ab. Daraus folgt, dass man sich nicht darum kümmern muss, wie eine Funktion genau realisiert ist, die beispielsweise die Datenbank anspricht. Über die API erhält man eine standardisierte Möglichkeit, eine bestimmte Aufgabe durchzuführen – im Hintergrund passieren dann vielleicht ganz viele Dinge, wie Sicherheitsüberprüfungen, Umwandlungen oder Transformationen. Dies geschieht im Idealfall allerdings im Backend – ohne dass der Anwender der API-Funktion davon etwas mitbekommt.
TYPO3 hat über die Jahre einige Schnittstellen implementiert bekommen, die die Arbeit eines Programmierers in vielen Punkten erleichtern. Was allerdings fehlt, ist eine übersichtliche Darstellung dieser API-Funktionen. Es gibt natürlich eine englische Dokumentation „TYPO3 Core API“ [1], diese ist aber für Anfänger relativ schlecht zu verdauen, da sie aus Sicht eines fortgeschrittenen TYPO3-Programmierers geschrieben ist, der eigentlich bereits über alle Details des TYPO3-Kerns Bescheid weiß. So gestaltet sich diese Dokumentation mehr wie eine technische Auflistung der verschiedenen Funktionen. Aber fangen wir einen Schritt davor an und erläutern erst einmal, welche Bereiche der API wie zusammenhängen.
Die Trennung der APIs zwischen Backend und Frontend macht durchaus Sinn, wenn man bedenkt, dass ein Backend-User für die Eingabe der Inhalte ganz andere Funktionen benötigt als ein Frontend-User, der nur auf der Website surft und dort vielleicht ein Formular ausfüllt. Trotzdem gibt es aber immer wieder Bereiche, die sowohl im Backend wie auch im Frontend gleichermaßen benötigt werden – diese werden in einer allgemeinen API, der „Common API“, zusammengefasst.
In der Backend-API finden sich folglich Funktionen, die angesprochen werden können, wenn man sich im Kontext des Backends befindet – also beispielsweise für Funktionen innerhalb eines Backendmoduls. Aber selbst die Core-Funktionen, die für das Backend zuständig sind, verwenden konsequent diese API.
Die Frontend-API wiederum findet vor allem in selbstgeschriebenen Extensions Verwendung. Dort kann der Extension-Programmierer schnell und einfach auf die benötigten TYPO3-Funktionen – wie zum Beispiel das Frontend-Session-Management – zugreifen.
In diesem Artikel soll allerdings zunächst die allgemeine TYPO3-API erläutert werden. In der nächsten T3N-Ausgabe folgen dann die Backend- und Frontend-APIs.
Die allgemeine TYPO3-API
Über die allgemeine TYPO3-API werden alle Funktionen zusammengefasst, die man weder ausschließlich dem Backend noch dem Frontend zuordnen kann. Beide Bereiche müssen auf die dort enthaltenen Funktionen zugreifen, daher werden die zugehörigen Klassen auch in beiden Bereichen gleichermaßen eingebunden.
In der nachfolgenden Grafik haben wir die wichtigsten Bereiche der allgemeinen API aufgeführt. Darüber hinaus existieren noch zahlreiche weitere Schnittstellen, die allerdings auch oft weniger wichtig sind beziehungsweise oft ausschließlich vom TYPO3-Kern eingesetzt werden und daher für die Extension-Entwicklung eher zweitrangig sind.
Kein direktes SQL durch Datenbank-Abstraktion
Mit der Datenbank-Abstraktions-API werden alle Zugriffe zur Datenbank gekapselt. Wenn man auf diese API zugreifen möchte, muss man lediglich angeben, welche Datenbanktabellen und Felder man wie ansprechen möchte. Alles andere erledigt die API bequem im Hintergrund. So ist es zum Beispiel möglich, neben MySQL auch andere Datenbanksysteme einzusetzen – die API erledigt hierbei über die Abstraktionsschicht die Vermittlung zwischen verschiedenen Datenbank-Systemen (zum Beispiel auch PostgreSQL und Oracle) und der angeforderten Funktion seitens der Extension (zum Beispiel Speichern einer Newsmeldung).
Beim Beispiel der Datenbank-Anbindung wird auch deutlich, welche Vorteile bei der Verwendung von APIs neben Bequemlichkeit und Schnelligkeit noch eine Rolle spielen. Würde man nämlich in seiner Extension den Zugriff auf eine MySQL-Datenbank direkt mit SQL-Befehlen implementieren und dann später entscheiden, auf eine andere Datenbank zu wechseln, müsste man alle Datenbank-Abfragen neu implementieren. Das mag noch halbwegs funktionieren, wenn man selbst der Autor der Extension ist, wird aber spätestens dann zu einem Problem, wenn man seine Erweiterungen der Allgemeinheit zur Verfügung stellt und man die Nutzung von verschiedenen Datenbank-Systemen ermöglichen möchte.
Klassendatei: t3lib/t3lib_DB.php Anzahl Funktionen: 42 Zugriff vom Frontend: $GLOBALS['TYPO3_DB'] Zugriff vom Backend: $GLOBALS['TYPO3_DB']
Listing 1
Exemplarisch wollen wir an dieser API aufzeigen, wie APIs im Allgemeinen zu lesen sind und was die gewonnenen Informationen im Detail bedeuten.
Um sich nun einen Überblick über die vorhandenen API-Funktionen zu verschaffen, sollte man die oben genannte Klassendatei „t3lib/t3lib_DB.php“ einmal näher betrachten. Nach dem Öffnen in einem Editor finden Sie um Zeile 36 herum den Kommentar „[CLASS/FUNCTION INDEX of SCRIPT]“ und darauf folgend die Funktionsdefinitionen schön übersichtlich hinter den Kommentaren aufgelistet, mit deren Hilfe man sich direkt und schnell einen Überblick über die in der Klasse vorhandenen Funktionen verschaffen kann. Vor den Definitionen steht jeweils die Zeilennummer, ab welcher die Funktion ausformuliert im Quelltext steht.
Mit etwas Übung benötigt man mit der Zeit nur diese Definition und kann daraus direkt lesen, was die Funktion macht und welche Parameter man ihr dafür übergeben muss. Ist allerdings die Wirkungsweise gänzlich unklar oder versteht man den einen oder anderen Parameter nicht, so kann man direkt zur angegebenen Zeilennummer gehen und dort im Code nachsehen, wie die Funktion im Detail realisiert wurde.
Aus der folgenden Auflistung der Funktionen (die mittels Kommentare auch noch in weitere Sektionen unterteilt sind) können Sie sich schnell einen Überblick über die vorhandenen API-Funktionen verschaffen:
* [CLASS/FUNCTION INDEX of SCRIPT] ... * 138: class t3lib_DB ... * SECTION: Query execution * 175: function exec_INSERTquery($table,$fields_values,$no_quote_fields=FALSE) * 192: function exec_UPDATEquery($table,$where,$fields_values,$no_quote_fields=FALSE) * 206: function exec_DELETEquery($table,$where) * 225: function exec_SELECTquery($select_fields,$from_table,$where_clause,$groupBy='',$orderBy='',$limit='') ... * SECTION: MySQL wrapper functions * 788: function sql_num_rows($res) * 800: function sql_fetch_assoc($res) ...
Listing 2
Wir wollen nun eine der API-Funktionen ausprobieren und erstellen uns hierfür eine Demo-Extension vom Typ „Frontend Plugin“. Wie man eine Extension erstellt, wurde sehr schön in T3N Nr. 10 erklärt [2]. Zudem gibt es zahlreiche Tutorials im Web, wie beispielsweise unter [3] oder [4].
Nachdem wir die Extension erstellt und so eingebunden haben, dass der Demo-Inhalt im Frontend angezeigt wird, können wir die zugehörige Datei „typo3conf/ext/tx_demoextension/pi1/class.tx_demoextension_pi1.php“ in einem Editor öffnen. Nun schreiben wir anstelle der Variablenzuweisung „$content=“ unseren eigenen Code. Wir wollen hier exemplarisch zeigen, wie wir die Datenbank-API ansprechen können:
<?php ... class tx_demoextension_pi1 extends tslib_pibase { ... function main($content,$conf) { $this->conf=$conf; $this->pi_setPiVarDefaults(); $this->pi_loadLL(); $res = $GLOBALS['TYPO3_DB']->exec_SELECTquery("*","be_users","admin=1"); while($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res)) { $content .= "User: ".$row['username'] ." hat Admin-Rechte<br/>"; } ... return $this->pi_wrapInBaseClass($content); } } ... ?>
Listing 3
Diese Extension liest alle Backend-User aus der Tabelle „be_user“ und filtert diejenigen heraus, die den Status „Admin“ haben. Somit erhalten wir alle Administratoren. Dafür haben wir zwei der zahlreichen Datenbank-API-Funktionen verwendet. Wir brauchen uns somit überhaupt keine Gedanken darüber machen, welche Datenbank nun genau angesprochen werden soll und wie die Zugangsdaten hierfür lauten. Die API regelt dies für uns automatisch im Hintergrund.
Extension-Management
In dieser API werden alle Funktionen gekapselt, die für die Verwaltung der Extensions notwendig sind. So finden sich hier Funktionen, die überprüfen, ob eine Extension bereits geladen ist oder wie der Pfad zu einer Extension genau lautet. In dieser API befinden sich noch zahlreiche andere nützliche Funktionen. Diese werden allesamt statisch angesprochen:
- Extension-Pfade und Evaluierung
- Frontend-Features (Hinzufügen von Plugins, Flexforms-Werten, TypoScript Setup (und Constants) und Static Templates)
- Backend-Features (Hinzufügen von Modulen und Funktionen zu Modulen, dynamisches Hinzufügen von TCA-Columns, Hinzufügen von PageTSconfig und UserTSconfig)
- Services (Services hinzufügen, Services finden, Services deaktivieren)
Klassendatei: t3lib/class.t3lib_extmgm.php Anzahl Funktionen: 32 Zugriff vom Frontend: t3lib_extMgm:: Zugriff vom Backend: t3lib_extMgm::
Listing 4
Hilfsfunktionen (Diverse)
Diese sehr bekannte und auch wohl umfassendste API ist im Grunde genommen der Sammelbehälter für alles, was in keiner anderen API Platz gefunden hat. Da es auch hier keinen Sinn machen würde, die enthaltenen Funktionen in einem Objekt zu kapseln, werden diese ebenfalls statisch angesprochen. Dort enthalten sind zahlreiche wichtige und hilfreiche Funktionen aus den folgenden Bereichen:
- Umgebungsvariablen (GET/POST)
- Bildfunktionen
- Funktionen zur Behandlung von Zeichenketten
- Funktionen zur Behandlung von Arrays
- HTML/XML-Verarbeitung
- Dateifunktionen
- Debug-Funktionen
- Systeminformation
- TYPO3-spezifische Funktionen
Klassendatei: t3lib/class.t3lib_div.php Anzahl Funktionen: 138 Zugriff vom Frontend: t3lib_div:: Zugriff vom Backend: t3lib_div::
Listing 5
Sprachen- und Characterset-Handling
In diesem Bereich werden alle Funktionen zusammengefasst, die im weitesten Sinne mit Sprachen und Zeichensätzen zu tun haben.
Klassendatei: t3lib/class.t3lib_div.php typo3/sysext/lang/language.php Anzahl Funktionen: 35 + 12 = 47 Zugriff vom Frontend: $csconv = t3lib_div::makeInstance('t3lib_cs'); $language = t3lib_div::makeInstance('language'); Zugriff vom Backend: $csconv = t3lib_div::makeInstance('t3lib_cs'); $language = t3lib_div::makeInstance('language');
Listing 6
Referenz-Index
Hier befinden sich alle Funktionen, die für die Erstellung, Pflege und Überprüfung des Referenz-Index in TYPO3 benötigt werden. Der Referenz-Index verwaltet Verweise zwischen TYPO3-Objekten, z. B. wenn mehrere Navigationselemente auf die gleichen Inhalte verweisen. Gerade bei eigenen Extensions sollte man immer Sorge dafür tragen, dass der Referenz-Index auf dem neuesten Stand ist.
Klassendatei: t3lib/class.t3lib_refindex.php Anzahl Funktionen: 18 Zugriff vom Frontend: $refIndex = t3lib_div::makeInstance('t3lib_refindex'); Zugriff vom Backend: $refIndex = t3lib_div::makeInstance('t3lib_refindex');
Listing 7
Weitere Informationen zum internen Aufbau von TYPO3 finden Sie auch im Dokument „Inside TYPO3“ [5] und „TYPO3 Coding Guidelines“ [6] auf typo3.org. Im nächsten Teil unserer Artikelserie wird es um die Backend- und Frontend-APIs gehen.
Die weiteren Artikel der Serie erscheinen in den nächsten T3N-Ausgaben: | |
Teil 1 (T3N Nr. 13) | Tour de Core |
Teil 2 (T3N Nr. 14) | Allgemeine APIs |
Teil 3 (T3N Nr. 15) | Backend- und Frontend-APIs |
Teil 4 (T3N Nr. 16) | TCA, Flexforms, Ajax |