< API-Dokumentation | Entwicklungs-HOWTO | Datenbankzugriffe >
Grundsätzlich liegt der Schlüssel zum Verständnis des Stud.IP-Codes in dem Satz "Stud.IP ist eine Datenbank". Das heißt: Alle für Stud.IP relevanten Informationen liegen in einer relationalen Datenbank und was die Weboberfläche in Form von PHP-Scripten leistet, sind mehr oder minder abstrahierte Sichten und Manipulationen dieser Datenbank. Aktuelle Entwicklungsparadigmen verlangen eine stärkere Abstraktion von der Datenbankschicht, als Stud.IP das in seiner fast 10jährigen Historie bislang umgesetzt hat. Der Trend ist klar: Weniger direkte Datenbankzugriffe, verstärkte Nutzung von verkapselnden Objekten und Funktionen, die auf längere Sicht eine interne Stud.IP-API bilden werden.
In diesem Abschnitt werden die bereits vorhandenen Ansätze zur Etablierung einer internen Programmier-API vorgestellt und damit aktuelle Empfehlungen für neu zu produzierenden oder zu überarbeitenden Code gegeben. Noch vorhandene, aber als veraltet angesehene Zugriffsweisen werden in speziellen Abschnitten mit den Stichwort "veraltet" dargestellt, außerdem wird der Bezug zur Datenbank durch Hinweise auf die tatäschlichen Speicherorte in Tabellen und Tabellenspalten hergestellt.
1. Zugriff auf Userdaten
User sind über zwei systemweit eindeutige Kennzeichen zu identifizieren: Die user_id
und der username
. Der Username, eine vom Nutzer selbstgewählte oder aus einem zur Authentifizierung genutzten System übernommene Zeichenkette kann sich ändern, die user_id, ein von Stud.IP generierter MD5-Hash nicht.
1.1 user_id und username des aktuellen Nutzers
Informationen über den Nutzer, für den das Script gerade ausgeführt wird, findet sich im global bekannten Objekt $user
, das von page_open()
initialisiert wird.
Darüber lassen sich verschiedene Informationen gewinnen:
$GLOBALS['user']->id
: user_id
des aktuellen Nutzers
$GLOBALS['user']->username
: username
des aktuellen Nutzers
Anmerkung: In Stud.IP-Installationen älter als v2.2 wurde inzwischen veraltetet so auf diese Daten zugegriffen: $auth->auth["uid"]
bzw. $auth->auth["uname"]
Um zu prüfen, ob die gegenwärtige Session authentifiziert ist, ruft man $GLOBALS['auth']->is_authenticated()
auf.
1.2 Rechte des aktuellen Nutzers
Jeder Nutzer hat verschiedene Rechte im System, die über das global bekannte Objekt $perm
zugänglich sind, das ebenfalls von page_open()
initialisiert wird.
Globale Rechte
Die globale Rechtestufe wird über die Methode $perm->get_perm()
erfragt, bzw. über $perm->have_perm(<rechtestufe>)
geprüft. Mögliche Werte für Rechtestufen sind nobody
, user
, author
, tutor
, dozent
, admin
und root
. Die Methode $perm->check(<rechtestufe>)
wird wie have_perm verwendet, liefert jedoch im Misserfolgsfall nicht FALSE
zurück, sondern erzeugt eine Stud.IP-Seite mit einer Zugriffsfehlermeldung und beendet die Ausführung des aktuellen Scripts.
$perm->have_perm(<rechtestufe>)
und $perm->check(<rechtestufe>)
prüfen nicht exakt, sondern betrachten die übergebene Stufe als Mindeststufe. perm->have_perm('dozent')
liefert also TRUE
, wenn der aktuelle Nutzer die globale Rechtestufe 'dozent', 'admin' oder 'root' hat.
Beispiele:
// ist der eingeloggte Nutzer Admin?
if ($perm->have_perm('admin')) {
...
}
// welche Rechtestufe hat der Nutzer global?
$p = $perm->get_perm();
Datenbankinfo: Die globale Rechtestufe ist in auth_user_md5.perm
gespeichert.
Veranstaltungs- und einrichtungsbezogene Rechte
In jeder Veranstaltung und jeder Einrichtung kann ein Nutzer über Rechte verfügen, die von seiner globalen Rechtestufe abweichen können. Der Zugriff auf veranstaltungs- und einrichtungsbezogene Rechtestufen geschieht über die Methoden $perm->get_studip_perm($range_id)
und $perm->have_studip_perm(<rechtestufe>,$range_id)
. Die range_id
ist die seminar_id
oder institut_id
der zu überprüfenden Veranstaltung oder Einrichtung (jeweils MD5-Hashes).
$perm->have_studip_perm(<rechtestufe>,$range_id)
prüft, ob der Nutzer mindestens über die angefragte Rechtestufe in der Veranstaltung bzw. der Einrichtung verfügt (s.o.).
Beispiele:
// ist der eingeloggte Nutzer mindestens Tutor in Veranstaltung $sem_id?
if ($perm->have_studip_perm('tutor', $sem_id)) {
...
}
// welche Rechtestufe hat der Nutzer in der Veranstaltung $sem_id?
$p = $perm->get_studip_perm($sem_id);
Datenbankinfo: Veranstaltungsbezogene Rechtestufen sind in seminar_user.perms
abgelegt, die einrichtungsbezogenen Rechtestufen in institute_user.perms
.
Veraltet: An vielen alten Stellen des Stud.IP-Codes wird auf die globale Variable $rechte
zugegriffen, in der als boolscher Wert abgelegt ist, ob der aktuelle Nutzer in der gewählten Einrichtung oder Veranstaltung mindestens über Tutorenrechte verfügt. Diese Variable sollte in neuem Code nicht mehr verwendet werden. Stattdessen ist der Ausdruck $perm->have_studip_perm('tutor', $SessSemName[1])
zu verwenden.
1.3 Zugriff auf weitere Nutzerdaten, Nutzer anlegen und löschen
Die Klasse UserManagement
kapselt viele Aktionen, die mit Nutzerdaten regelmäßig durchgeführt werden. Sie ist vor allem entstanden, um die vielfältigen Aktionen rund um Neuanlegen und Löschen eines Nutzers an einer Stelle zusammenzufassen und z.B. Authentifizierungsplugins zugänglich zu machen.
Eine Detaildokumentation der verfügbaren Methoden sollte direkt dem Quellcode entnommen werden: http://develop.studip.de/trac/browser/trunk/lib/classes/UserManagement.class.php
Datenbankinfo: die von der Klasse UserManagement
berührten Daten liegen vor allem in den Tabellen auth_user_md5
und user_info
.
Veraltet: Jeglicher Code, der INSERT oder DELETE Statements gegen die Tabellen auth_user_md5
und user_info
absetzt, ist als veraltet zu betrachten. Für alle Aktionen zum Erzeugen und Löschen von Nutzern sollte die Klasse UserManagement
verwendet werden.
1.4 Voreinstellungen des Nutzers
Die Nutzer können sich "ihr" Stud.IP mit einer Reihe von persönlichen Konfigurationsoptionen verändern. Sei es die nach dem Login angezeite Startseite, die Sprache, die bevorzugte Sortierung aus der Seite "Meine Seminare".
Der für alle Neuentwicklungen vorgesehene Weg führt über die Klasse UserConfig
. Darüber lassen sich nutzerspezifische Einstellungen abrufen und speichern.
Methoden und typische Verwendungsweise der Klasse sind:
* Usage:
*
*
$uc=UserConfig
() // construct without implicit user/key
*
$uc=UserConfig
($someuser_id,
"somekey");
// construct and set implicit user/key
*
*
$v=
$uc->
getValue();
// get value for "someuser" and "somekey"
*
$v=
$uc->
getValue($otheruser_id,
$somekey);
// get value for "otheruser" and "somekey"
*
$v=
$uc->
getValue(NULL,
"otherkey");
// get value for "someuser" and "otherkey"
*
$v=
$uc->
getValue($otheruser_id,
"otherkey");
// get value for "otheruser" and "otherkey"
*
*
$uc->
setValue("somevalue");
// set value to "somevalue" for "someuser"/"somekey"
* ... combinations of explicit user_id and
key same
as getValue
(...
) ...
*
*
$uc->
unsetValue();
// unset (delete from db) value for "someuser"/"somekey"
* ... combinations of explicit user_id and
key same
as getValue
(...
) ...
*
*
$uc->
unsetAll($user_id);
// delete all entries for a user (user_id explicit or implicit)
*
$uc->
getAll($user_id);
// get all entries for a user (user_id explicit or implicit)
*
*
$uc->
setUserId($otheruser_id);
// switch to "otheruser" for implict get/set
*
$uc->
setKey("otherkey");
// switch to "otherkey" for implict get/set
*
Veraltet: In früheren Codeteilen wurden Nutzereinstellung zumeist in dauerhaften Session-Variablen gespeichert. Beispiele für diese Verwendung liefert die Datei lib/mystudip.inc mit der globalen Variablen $my_studip_settings
. Für neuen Code darf diese Praxis nicht mehr angewandt werden.
2. Zugriff auf Veranstaltungsdaten