>> Inhaltsverzeichnis >> Anleitung für Entwickler >> Referenzhandbuch

Anleitung für Entwickler

Referenzhandbuch

Funktionsreferenz

getConfigFile

mixed getConfigFile( string $filename[, boolean $upper_case ] )

 

Parameter

Typ

Beschreibung

filename

string

Name der zu ladenden Konfigurationsdatei

upper_case

boolean

true = alle Bezeichner werden in Großbuchstaben gewandelt

false = Schreibweise der Bezeichner wird beibehalten

Defaultwert = true

Parameterliste getConfigFile

Lädt die angegebene Konfigurationsdatei im SML-Format und liefert den Inhalt als PHP-Variable zurück.

makeConfig

string makeConfig( mixed $value
[, string $name
[, boolean $upper_case ]] )


Parameter

Typ

Default

Beschreibung

value

mixed

n/a

Wert der Variable

name

string

null

Bezeichner des Wurzelelements (null=keiner)

upper_case

boolean

true

  • true: alle Bezeichner werden in Großbuchstaben gewandelt

  • false: Schreibweise der Bezeichner wird beibehalten

Parameterliste makeConfig

Erzeugt für die übergebene Variable eine Darstellung als SML-Code und liefert diesen als String zurück. Es muss sich entweder um eine Variable mit einem skalaren Wert oder ein eventuell mehrdimensionales Datenfeld skalarer Werte handeln.

Die Funktion „makeConfig“ erkennt keine unendlichen Rekursionen. Daher müssen die Datenfelder rekursionsfrei sein. Andernfalls wird durch den Compiler eine Fehlermeldung erzeugt.

dirlist

array dirlist( string $directory[, string $filter ] )


Parameter

Typ

Default

Beschreibung

directory

string

n/a

Zielverzeichnis

filter

string

„“

Dateifilter

Parameterliste dirlist

Liefert für ein Verzeichnis eine sortierte Liste der enthaltenen Dateien und Verzeichnisse als numerisches Datenfeld zurück. Die obligatorischen Verzeichniseinträge „.“ und „..“ werden nicht aufgelistet. Dateien, deren Dateinamen mit dem Zeichen „.“ beginnen werden nicht aufgelistet. Das betrifft insbesondere Dateienamen wie „.htaccess“ oder „.password“. Alle Angaben enthalten keine Pfadangaben. Verzeichnisnamen enthalten keinen abschliessenden Querstrich „/“.

Der optionale Parameter $filter kann verwendet werden um die Ausgabe auf bestimmte Dateiendungen zu beschränken. Wildcards sind nicht gestattet. Der Dateifilter darf lediglich alphanumerische Zeichen, sowie die Zeichen '.', '-' und '_' enthalten. Andere Zeichen werden beim Aufruf der Funktion automatisch entfernt.

Beispiel:

echo implode("<br>", dirlist('config/', '*.config'));

Ausgabe:
_date.config
_drive.config
_loader.config
_plugins.config
_user.config

send_mail

boolean send_mail( string $recipient, string $subject, string $text [, array $header ] )


Parameter

Typ

Default

Beschreibung

recipient

string

n/a

Mailadresse des Empfängers der Nachricht

subject

string

n/a

Betreff der Nachricht

text

string

n/a

Text der Nachricht

header

array

array()

Assoziatives Datenfeld der Header-Informationen

Parameterliste send_mail


Die Funktion „send_mail“ ist eine gegen Missbrauch und „Header-Injection“ abgesicherte Variante der nativen PHP-Funktion „mail“. Anders als „mail“ werden alle Eingabedaten geprüft und auch nicht alle Header-Informationen, welche „mail“ prinzipiell gestattet sind erlaubt.

Es wird „true“ zurückgegeben, wenn die Mail versandt werden konnte, „false“ sonst. Der Wert „true“ bedeutet jedoch nicht, dass die Mail erfolgreich zugestellt wurde. Er bedeutet lediglich, dass die Eingabedaten im Sinne dieser Funktion syntaktisch korrekt waren.

Die Funktion erzeugt im Header der Mail die zusätzlichen Einträge „x-yana-php-header-protection“ und „x-yana-php-spam-protection“.

Aus Sicherheitsgründen gelten folgende Einschränkungen.

Parameter

Typ

Default

Beschreibung

from

mail

n/a

Eine gültige Mailadresse

return-path

mail

n/a

Eine gültige Mailadresse

cc

mixed

n/a

Entweder eine gültige Mailadresse oder ein numerisches Datenfeld mit mehreren Mailadressen. An alle angegebenen Adressen wird eine Kopie der Nachricht versandt. Anders als bei „bcc“ ist die Liste der Empfänger jedoch für alle Empfänger sichtbar.

content-type

string

text/plain;
charset="8859-1"

Bestimmt den MIME-Type der Nachricht. Nur MIME-Type und Charset sind als Eingaben erlaubt. Andere Werte werden ignoriert.

mime-version

float

1.0

Angabe muss entsprechend folgendes regulären Ausdrucks erfolgen (Perl-Syntax): /^\d\.\d$/

content-transfer-encoding

string

n/a

Angabe muss entsprechend folgendes regulären Ausdrucks erfolgen (Perl-Syntax): /^\d{,2}bit$/i

gültige Werte für Parameter header Funktion send_mail

Die Verwendung von „BCC“ ist aus Sicherheitsgründen nicht gestattet.

untaintInput

mixed untaintInput( mixed $value
[, string $type [, integer $length [, integer $escape ]]] )


Parameter

Typ

Default

Beschreibung

value

mixed

n/a

zu säuberndes Datum

type

string

„“

Datentyp

Neben den von PHP unterstützten nativen Typen sind noch folgende Werte erlaubt:

  • time: UTC-Zeitcode (Typ Integer, Länge 11)

  • ip: IP-Adresse (Typ String, Länge 15)

  • mail: Mailadresse (Typ String)

  • select: wird behandelt wie „string“

  • text: wird behandelt wie „string“

length

integer

0

Maximale Länge des Datums

escape

integer

0

siehe Tabelle

Parameterliste untaintInput

Der Parameter $escape kann mit einer der folgenden Konstanten belegt werden.

Bezeichner

Beschreibung

YANA_ESCAPE_NONE

keine Änderungen durchführen (Default)

YANA_ESCAPE_SLASHED

wandelt einfache und doppelte Anführungszeichen in ihre entsprechenden Escapesequenzen in C-Syntax um

YANA_ESCAPE_TOKEN

ersetzt enthaltene Token durch ihre HTML-Entities

YANA_ESCAPE_CODED

ersetzt HTML-Symbole, beispielsweise Tagklammern, durch Entities

YANA_ESCAPE_LINEBREAK

wandelt alle Whitespace-Zeichen (insbesondere Zeilenumbrüche) in Leerzeichen um

Gültige Belegungen für den Parameter $escape der Funktion untaintInput

Dient dem Säubern eines Eingabedatums bevor es in eine Datenbank oder Datei geschrieben wird.

Klassenreferenz

Im Folgenden werden die öffentlichen Schnittstellen der wichtigsten Klassen beschrieben, welche für Entwickler gedacht sind. Klassen, welche nur für interne Funktionen des Frameworks bestimmt sind, werden nicht genannt. Nicht-öffentliche Attribute oder Methoden, oder solche, welche als nicht-öffentlich konzipiert sind, werden ebenfalls nicht aufgeführt.

BufferedDbStream

Die Klasse „BufferedDbStream“ ist für Datenbankzugriffe gedacht.

BufferedDbStream::BufferedDbStream()

BufferedDbStream BufferedDbStream( [string $filename
[, DbServer $server]] )


Parameter

Typ

Default

Beschreibung

filename

string

„“

Name und Pfad der Strukturdatei, falls vorhanden

server

DbServer

null

Enthält die Konfiguration der Verbindung zum Datenbankserver

Parameterliste BufferedDbStream::BufferedDbStream()

Erzeugt eine neue Instanz der Klasse „BufferedDbStream“

BufferedDbStream::get()

mixed get(string $key [, string $search [, string $filter ]] )


Parameter

Typ

Default

Beschreibung

key

string

n/a

Adresse des gewünschten Datums, beziehungsweise Datensatzes.

Als Wildcard ist das Zeichen „*“ gestattet

search

string

„“

Liste von Vergleichswerten (WHERE-Klausel)

Syntax: „feldname=wert[,feldname=wert[...]]

filter

string

„“

Sonstige Angaben, wie LIMIT-Klausel oder Sortierung

Parameterliste BufferedDbStream::get()

Führt eine Select-Anfrage auf der Datenbank aus und liefert den Wert an der Stelle zurück, welche mit dem Parameter „key“ angegeben wurde.

Im Folgenden einige Beispiele:

Feld ausgeben:
$db = new BufferedDbStream();
$value = $db->get(„table.2.field“,„row1=wert1,row2=wert2“,„limit 1“);
echo $value;


Erzeugt folgende SQL-Anfrage:
SELECT field from table where primary_key = „2“ and row1 like '%wert1%' and row2 like '%wert2%' limit 1;


Spalte ausgeben:
$db = new BufferedDbStream();
$column = $db->get(„table.*.field“,„row1=wert1,row2=wert2“);
foreach ($column as $row => $value)
{
echo „<p>Value of field in row $row = $value</p>“;
}


Erzeugt folgende SQL-Anfrage:
SELECT field from table where row1 like '%wert1%' and row2 like '%wert2%';


Zeile ausgeben:
$db = new BufferedDbStream();
$row = $db->get(„table.2“);
foreach ($row as $column => $value)
{
echo „<p>Value of column $column in row 2 = $value</p>“;
}


Erzeugt folgende SQL-Anfrage:
SELECT * from table where primary_key = „2“;


Tabelle ausgeben:
$db = new BufferedDbStream();
$table = $db->get(„table.*“);
foreach ($table as $index => $row)
{
foreach ($row as $column => $value)
{
echo „<p>Value at table.$index.$column = $value</p>“;
}
}


Erzeugt folgende SQL-Anfrage:
SELECT * from table where primary_key = „2“;

BufferedDbStream::insert()

boolean insert(string $key, mixed $value [, string $filter ] )


Parameter

Typ

Default

Beschreibung

key

string

n/a

Adresse des gewünschten Datums, beziehungsweise Datensatzes.

Als Wildcard ist das Zeichen „*“ gestattet

value

string

n/a

Wert, der eingefügt werden soll

filter

string

„“

Sonstige Angaben, wie LIMIT-Klausel oder Sortierung

Parameterliste BufferedDbStream::insert()

Fügt den Wert „value“ an der Stelle „key“ ein. Dabei kann es sich entweder um eine Zeile oder eine Tabellenzelle handeln. Das Einfügen von Tabellen oder Spalten ist nicht möglich.

Falls die Zeile nicht existiert, wird ein die SQL-Anweisung „insert“ benutzt, sonst „update“.

Gibt bei Erfolg „true“ zurück und „false“ sonst.

Achtung! Die SQL-Anweisung wird erst ausgeführt, wenn die Funktion BufferedDbStream::write() aufgerufen wird. Falls die Funktion BufferedDbStream::insert() mehrmals aufgerufen wird, bevor Sie die Funktion BufferedDbStream::write() aufrufen, werden alle diese Zugriffe nacheinander im Rahmen einer gemeinsamen Transaktion ausgeführt. Schlägt eine der Anweisungen fehl, wird automatisch ein Rollback durchführt.

Im Folgenden einige Beispiele:

Neue Zeile einfügen:
$db = new BufferedDbStream();
$db->insert(„table.*“,array(„row1“=>“wert1“,“row2“=>“wert2“));
$db->write();


Zeile aktualisieren:
$db = new BufferedDbStream();
$db->insert(„table.2“,array(„row1“=>“wert1“,“row2“=>“wert2“));
$db->write();


Zelle aktualisieren:
$db = new BufferedDbStream();
$db->insert(„table.2.row1“,“wert1“);
$db->write();


Transaktion durchführen:
$db = new BufferedDbStream();
$db->insert(„table.*“,array(„row1“=>“wert1“,“row2“=>“wert2“));
$db->insert(„table.*“,array(„row1“=>“wert3“,“row2“=>“wert4“));
$db->insert(„table.1.row3“,“wert1“);
$db->write();

BufferedDbStream::remove()

boolean remove(string $key, [, string $search ] )


Parameter

Typ

Default

Beschreibung

key

string

n/a

Adresse des gewünschten Datums, beziehungsweise Datensatzes.

Als Wildcard ist das Zeichen „*“ gestattet

search

string

„“

Liste von Vergleichswerten (WHERE-Klausel)

Syntax: „feldname=wert[,feldname=wert[...]]

Parameterliste BufferedDbStream::remove()

Löscht den Datensatz an der Adresse „key“ aus der Tabelle.

Gibt bei Erfolg „true“ zurück und „false“ sonst.

Achtung! Die SQL-Anweisung wird erst ausgeführt, wenn die Funktion BufferedDbStream::write() aufgerufen wird.

BufferedDbStream::join()

boolean join(string $t1 [, string $t2 [,string $k1 [,string $k2 ]]] )


Parameter

Typ

Default

Beschreibung

t1

string

n/a

Tabelle 1

t2

string

„“

Tabelle 2

k1

string

„“

Feld 1

k2

string

„“

Feld 2

Parameterliste BufferedDbStream::join()

Verbindet zwei Tabellen über einen Join. Wenn keine Schlüssel angegeben werden, über welche die Identifizierung stattfinden kann, wird automatisch ein Natural-Join angewendet. Falls nur 1 Tabelle angegeben wurde, dann wird automatisch die zuletzt ausgewählte Tabelle als Ziel verwendet.

Wird automatisch bei jedem folgenden Zugriff auf die Tabelle angewendet.

BufferedDbStream::query()

mixed query(string $sql)


Parameter

Typ

Default

Beschreibung

sql

string

n/a

SQL-Statement

Parameterliste BufferedDbStream::query()

Erlaubt einen Bypass auf die PEAR-DB Schnittstelle. Liefert das Ergebnis der Anfrage zurück.

BufferedDbStream::getFilter()

String getFilter([string $table])


Parameter

Typ

Default

Beschreibung

table

string

„“

Name der gewünschten Tabelle

Parameterliste BufferedDbStream::getFilter()

Gibt die gerade gesetzten Filter für die Tabelle zurück.

BufferedDbStream::setFilter()

void setFilter(string $table, string $filter)


Parameter

Typ

Default

Beschreibung

table

string

n/a

Name der gewünschten Tabelle

filter

string

n/a

Wert

Parameterliste BufferedDbStream::setFilter()

Setzt den Filterwert (beispielsweise „limit“ oder eine Sortierung) in SQL-Syntax. Dieser Wert wird automatisch bei allen künftigen Anfragen auf die Tabelle angewendet.

BufferedDbStream::getTable()

String getTable()


Liefert den Namen der zuletzt ausgewählten Tabelle zurück.

BufferedDbStream::length()

int length([string $table [, string $search]])


Parameter

Typ

Default

Beschreibung

table

string

n/a

Name der gewünschten Tabelle

search

string

„“

Liste von Vergleichswerten (WHERE-Klausel)

Syntax: „feldname=wert[,feldname=wert[...]]

Parameterliste BufferedDbStream::length()

Liefert die Anzahl der Einträge zurück in der Tabelle zurück. Der Parameter „search“ kann verwendet werden, um die Anzahl der Einträge zu erhalten, welche den Kriterien entsprechen. Wird keine Tabelle angegeben, wird automatisch die zuletzt ausgewählte Tabelle verwendet.

BufferedDbStream::exists()

boolean exists([string $key])


Parameter

Typ

Default

Beschreibung

key

string

„“

Zu prüfende Adresse

Parameterliste BufferedDbStream::exists()

Liefert „true“, falls die mit „key“ angegebene Adresse (Tabelle, Zeile, Zelle) definiert ist und „false“ sonst. Falls kein Parameter angegeben wird, liefert die Funktion „true“ falls die Datenbankverbindung existiert und „false“ falls nicht.

BufferedDbStream::create()

boolean create(string $filename)


Parameter

Typ

Default

Beschreibung

filename

string

n/a

Name und Pfad einer SQL-Datei

Parameterliste BufferedDbStream::create()

Liest die Datei und führt die enthaltenen SQL-Anweisungen als Transaktion aus. Liefert „true“ bei Erfolg, sonst „false“.

Diese Funktion ist insbesondere für Installationsroutinen gedacht. Daher die Bezeichnung „create“.

BufferedDbStream::toString()

String toString([string $table])


Parameter

Typ

Default

Beschreibung

table

string

„“

Name der gewünschten Tabelle

Parameterliste BufferedDbStream::toString()

Liefert den Inhalt der gewählten Tabelle im CSV-Format zurück. Wird keine Tabelle angegeben, wird die zuletzt ausgewählte Tabelle verwendet. Im Fehlerfall wird „false“ zurück geliefert.

BufferedDbStream::exportStructure()

boolean exportStructure(string $filename)


Parameter

Typ

Default

Beschreibung

filename

string

n/a

Name und Pfad einer Zieldatei

Parameterliste BufferedDbStream::exportStructure()

Exportiert die gesammelten Informationen über die Struktur der Datenbank in die angegebene Datei. Gibt bei Erfolg „true“ und sonst „false“ zurück.

Counter

Klasse zum Erzeugen persistenter Zählerinformationen, beispielsweise für Besucherzähler etc.

Counter::Counter()

Counter Counter([string $filename])


Parameter

Typ

Default

Beschreibung

filename

string

„statistik“

Name der Zieldatei

Parameterliste Counter::Counter()

Erzeugt eine neue Instanz von Counter().

Empfehlung: als Parameter „filename“ kann der Name des Plugins verwendet werden.

Counter::count()

int count(string $id [, string $info [, int $ammount]])


Parameter

Typ

Default

Beschreibung

id

string

n/a

ID-Kennung des Zählers

info

string

„“

Beschreibung

ammount

integer

1

Zu addierende Zahl

Parameterliste Counter::count()

Addiert eine angegebene Zahl zu dem angegebenen Zähler.

Counter::get()

array get([string $id])


Parameter

Typ

Default

Beschreibung

id

string

„*“

ID-Kennung des Zählers

Parameterliste Counter::get()

Liefert Informationen über den angegebenen Zähler. Falls kein Zähler ausgewählt wurde, werden alle Zähler zurück geliefert.

Counter::getCount()

mixed get([string $id])


Parameter

Typ

Default

Beschreibung

id

string

„*“

ID-Kennung des Zählers

Parameterliste Counter::getCount()

Liefert den Zählerstand des angegebenen Zählers als String. Falls kein Zähler ausgewählt wurde, werden alle Zähler als Datenfeld zurück geliefert.

DirStream

Die Klasse „DirStream“ dient der Handhabung von Verzeichnissen.

DirStream::DirStream()

DirStream DirStream(String $path)


Parameter

Typ

Default

Beschreibung

path

string

n/a

Pfad des Verzeichnisses

Parameterliste DirStream::DirStream()

Erzeugt eine neue Instanz der Klasse „DirStream“

DirStream::read()

boolean read()

Öffnet das Verzeichnis zum Lesen. Gibt bei Erfolg „true“ zurück, sonst „false“.

DirStream::dirlist()

array dirlist(string $filter)

Parameter

Typ

Default

Beschreibung

filter

string

n/a

Filter für Dateiendung

Parameterliste DirStream::dirlist()

Diese Funktion bewirkt Folgendes:

  1. permanentes Setzen des Dateifilters auf den Wert $filter

  2. der Inhalt des Verzeichnisses wird neu gelesen unter Berücksichtigung des Dateifilters

  3. der gefilterte Inhalt wird als numerisches Datenfeld zurück gegeben

Beispiel:

$dir = new DirStream('./');
$content = $dir->dirlist('*.php');
echo implode(„, “, $content);


Ausgabe:
index.php, library.php

DirStream::length()

integer length()


Gibt die Anzahl der gefundenen Dateien zurück, falls ein Filter benutzt wird. Sonst wird die Anzahl der Dateien und Unterverzeichnisse insgesamt zurück geliefert. Wenn das Verzeichnis nicht zum Lesen geöffnet oder leer ist, gibt die Funktion „0“ zurück.

DirStream::create()

boolean create(integer $mode)


Parameter

Typ

Default

Beschreibung

mode

integer

n/a

Zugriffsrechte für das Verzeichnis gemäß Unix-Syntax.

Paramterliste DirStream::create()

Beispiele für gültige Werte für $mode finden Sie in der folgenden Tabelle. Dabei steht „r“ für „readable“, „w“ für „writeable“ und „x“ für „executeable“.

Besitzer

Gruppe

sonstige Nutzer

Wert

rwx

rwx

rwx

777

rw-

rw-

---

660

rw-

rw-

rw-

666

rwx

r-x

r-x

755

rwx

r-x

---

750

rwx

---

---

700

Beispiele für gültige Werte (entsprechend Unix: CHMOD)

Diese Funktion legt ein neues Verzeichnis an, mit den Rechten welche der Parameter „$mode“ bestimmt.

Gibt bei Erfolg „true“ und sonst „false“ zurück: beispielsweise wenn das Verzeichnis nicht existiert, die Rechte unzureichend sind oder die Syntax des Parameters „$mode“ nicht korrekt ist.

Mailer

Die Klasse „Mailer“ dient zum Versenden von Mails mithilfe einer Mailvorlage (Template).

öffentliche instanzspezifische Variablen
Mailer::send()

boolean send(String $recipient)


Parameter

Typ

Default

Beschreibung

recipient

string

n/a

Empfänger der Mail

Parameterliste Mailer::send()

Sendet eine Mail an den angegebenen Empfänger. Liefert „true“ bei Erfolg, sonst „false“.

ProgramLoader

Im Folgenden die wichtigsten öffentlichen Funktionen der Klasse „ProgramLoader“. Die Klasse „ProgramLoader“ ist ein Singleton. Sie ist über die globale Variable „YANA“ aus jedem Kontext erreichbar. Plugins kommunizieren in diesem Framework über Speicherkopplung.

Die Klasse „ProgramLoader“ dient als Controler der Kommunikation zwischen verschiedenen Schichten des Frameworks und dem Austausch von Informationen zwischen Plugins, indem es Zugriff auf den gemeinsamen Speicher gestattet.

ProgramLoader::getVar()

mixed getVar(String $key)


Parameter

Typ

Default

Beschreibung

key

string

n/a

Adresse des gewünschten Datums

Parameterliste ProgramLoader::getVar()

Lädt die Variable „key“ aus dem gemeinsamen Speicher aller Plugins und liefert diese zurück.

ProgramLoader::setVar()

boolean setVar(String $key, mixed $value)


Parameter

Typ

Default

Beschreibung

key

string

n/a

Adresse des gewünschten Datums

value

mixed

n/a

Neuer Wert des Datums

Parameterliste ProgramLoader::setVar()

Ändert den Wert der Variable „key“ im gemeinsamen Speicher. Liefert „true“ bei Erfolg, „false“ sonst.

ProgramLoader::unsetVar()

boolean unsetVar(String $key)


Parameter

Typ

Default

Beschreibung

key

string

n/a

Adresse des gewünschten Datums

Parameterliste ProgramLoader::unsetVar()

Löscht die Variable „key“ aus dem gemeinsamen Speicher. Liefert „true“ bei Erfolg, „false“ sonst.

ProgramLoader::message()

void message(String $level, String $code [, String $next])


Parameter

Typ

Default

Beschreibung

level

string

n/a

Art der Meldung. Mögliche Werte sind:

  • OK

  • ALERT

  • ERROR

code

string

n/a

ID-Kennung der gewünschten Meldung in der Sprachdatei „message.config“. Beispielsweise „LOGOUT“ oder „LOGIN_UNGUELTIG“

next

string

„“

Aktion, zu welcher nach Anzeigen der Textmeldung verwiesen werden soll

Parameterliste ProgramLoader::message()

Kommuniziert mit der Anzeigeschicht und erzeugt eine Textmeldung. Der Inhalt der Textmeldung kann nicht direkt angegeben werden, sondern wird aus der Sprachdatei, „message.config“ entsprechend der passenden Übersetzung zu den aktuellen Spracheinstellungen des Frameworks geladen.

Bei Aufruf dieser Funktion wird automatisch eine Ausgabe erzeugt und die Programmausführung wird unterbrochen. Der optionale Parameter „next“ gibt an, welche Aktion anschließend ausgeführt werden soll.

ProgramLoader::handle()

boolean handle(String $action, array $arguments)


Parameter

Typ

Default

Beschreibung

action

string

n/a

Name der Aktion, die ausgeführt werden soll

arguments

string

n/a

Parameterliste der Aktion als assoziatives Datenfeld

Parameterliste ProgramLoader::handle()

Diese Funktion bewirkt, dass das Framework die Implementierung aufruft, welche zu der angegebenen Aktion passt. Es wird die gegebene Parameterliste verwendet.

Liefert „true“ falls die Aktion erfolgreich war, sonst „false“.

Dateiformate : u.a. SmlFile, TextFile, DatFile, ConfigFile

Alle vom Framework unterstützten Dateiformate sind abgeleitet von der Klasse „secureFileStream“. Das heißt, alle bieten eine vergleichbare Schnittstelle.

Diese „gemeinsame“ Schnittstelle wird im Folgenden beschrieben. Insofern es für eine bestimmte Klasse Abweichungen gibt, werden diese entsprechend dokumentiert.

Interessante Variablen

Variable

Beschreibung

SecureInputStream::attributes['MTIME']

Datum der letzten Änderung, Format: „d.m.Y“

SecureInputStream::attributes['ATIME']

Zeit des letzten Zugriffs, Format: „d.m.Y H:i:s“

SecureInputStream::attributes['CTIME']

Datum der Erstellung der Datei, Format: „d.m.Y“

interessante Variablen der Klasse SecureInputStream

SecureInputStream::read()

boolean read()


Öffnet die Datei zum Lesen. Gibt bei Erfolg „true“ zurück, sonst „false“.

SecureInputStream::failSafeRead()

boolean failSafeRead()


Öffnet die Datei zum Lesen. Es werden 3 Verbindungsversuche in unregelmäßigen Zeitabständen durchgeführt. Erst wenn alle 3 Versuche erfolglos bleiben gilt das Öffnen der Datei als gescheitert. Gibt bei Erfolg „true“ zurück, sonst „false“.

SecureInputStream::get()

mixed get()


Liefert den Inhalt der Datei zurück. Parameter und Typ des Rückgabewertes ist abhängig von der Art der Datei.

SecureFileStream::length()

int length()


Gibt die Anzahl der Dateieinträge zurück.

SecureFileStream::insert()

void insert(array $param)


Fügt den Wert $param in den Dateipuffer ein. Typ des Eingabeparameters ist abhängig vom Typ der Datei entweder ein numerisches Datenfeld, wobei die Indexnummern den Zeilennummern der Datei entsprechen, oder ein (eventuell mehrdimensionales) assoziatives Datenfeld, wobei die Schlüssel der Adresse des jeweiligen Datensatzes in der Datei entsprechen – ähnlich einer Datenbank.

SecureFileStream::remove()

boolean remove([mixed $key])


Versucht den Wert an der durch den Parameter $key angegebenen Adresse der Datei aus dem Dateipuffer zu entfernen. Gibt bei Erfolg „true“ zurück, sonst „false“. Wird der Parameter $key nicht angegeben, wird der gesamte Inhalt des Puffers gelöscht.

SecureFileStream::create()

boolean create()


Versucht die aktuelle Datei zu erzeugen. Gibt bei Erfolg „true“ zurück, sonst „false“. Wenn die Datei bereits existiert liefert die Funktion „false“.

SecureFileStream::delete()

boolean delete()

Versucht die aktuelle Datei zu löschen. Gibt bei Erfolg „true“ zurück, sonst „false“.

SecureFileStream::write()

boolean write()


Versucht den Dateiinhalt aus dem Puffer auf das Dateisystem zu schreiben. Gibt bei Erfolg „true“ zurück, sonst „false“.

SecureFileStream::failSafeWrite()

boolean failSafeWrite()


Versucht den Dateiinhalt aus dem Puffer auf das Dateisystem zu schreiben. Es werden 3 Verbindungsversuche in unregelmäßigen Zeitabständen durchgeführt. Erst wenn alle 3 Versuche erfolglos bleiben gilt das Schreiben der Datei als gescheitert. Gibt bei Erfolg „true“ zurück, sonst „false“.

SecureInputStream::close()

void close()


Setzt alle Verbindungsdaten zurück.

SecureInputStream::checksum()

int checksum()


Liefert die CRC32-Prüfsumme der gerade geöffneten Datei zurück. Gut geeignet, um Änderungen der Quelldatei zu verfolgen.

SecureInputStream::isEmpty()

boolean isEmpty()


Liefert „true“ zurück, falls die Datei keinen Inhalt hat, oder nicht geöffnet wurde. Andernfalls liefert die Funktion „false“.

SecureFileStream::is_writeable()

boolean is_writeable()


Liefert „true“ zurück, falls die Datei zum Schreiben geöffnet werden kann, andernfalls „false“.

InputStream::exists()

boolean exists()


Liefert „true“ zurück, falls die Datei existiert, andernfalls „false“.

InputStream::getFilename()

string getFilename()


Gibt den Namen der Datei zurück.

Referenz der Standardbibliothek

Das Framework besitzt ein Plugin, welches unter der ID „default_library“ registriert ist. Diese Bibliothek ist für häufig gebrauchte Operationen gedacht und wird regelmäßig gepflegt und erweitert.

Im Folgenden eine Liste der Aktionen, welche diese Bibliothek entgegennimmt, sowie eine Beschreibung des erwarteten Verhaltens, sowie Liste der möglichen Parameter.

Die Standardbibliothek verwendet folgende Parameter:

plugin_default_library::clear_server_cache()

boolean $YANA->handle(„clear_server_cache“, array $ARGS);



Argument

Typ

Default

Beschreibung

target

string

null

Name der Aktion, welche anschließend ausgeführt werden soll. Die Schreibweise (Groß-/Kleinschreibung) wird nicht berücksichtigt.

akzeptierte Argumente der Aktion „clear_server_cache“

Diese Aktion bewirkt, dass alle Dateien mit den Endungen „*.php“ und „*.cache“ im Verzeichnis „cache/“ des Frameworks gelöscht werden. Dies erzwingt eine Aktualisierung des Cache.

Die Aktion gibt stets „true“ zurück. Wird der optionale Parameter „target“ gesetzt, so wird eine Ausgabe (Bestätigungsseite) erzeugt und anschliessend automatisch auf die angegebene Aktion weitergeleitet. Dadurch wird die Skriptausführung unterbrochen. Wird dieser Parameter nicht gesetzt, wird keine Ausgabe erzeugt und die Skriptausführung wird forgesetzt.

plugin_default_library::preview()

void $YANA->handle(„preview“, array $ARGS);



Argument

Typ

Default

Beschreibung

eintraege

string

n/a

Text, für welchen eine Vorschau erstellt werden soll.
Parameter ist Pflicht.

akzeptierte Argumente der Aktion „preview“

Diese Aktion ist dazu gedacht eine Vorschau auf einen Einträg, beispielsweise für Foren oder Gästebücher, zu erstellen und in einem Inline-Frame oder via AJAX in einem dafür vorgesehenen HTML-Element anzuzeigen.

Die Aktion wandelt in dem Text des Parameters „eintraege“ enthaltene Codes zur Darstellung von Textformatierungen und Emoticons in HTML um und gibt das Resultat als HTML aus. Wird der Parameter nicht angegeben, erzeugt der Aufruf eine Fehlermeldung.

Der Aufruf dieser Aktion unterbricht die aktuelle Ausführung des Skripts.

plugin_default_library::sitemap()

boolean $YANA->handle(„sitemap“, array $ARGS);


Diese Aktion erzeugt eine „Sitemap“. Also eine Auflistung aller derzeit installierten Anwendungen des Frameworks. Zu diesem Zweck wird der Parameter „START“ der Schnittstellenbeschreibung der installierten Plugins ausgewertet. Dieses Attribut gibt den Namen einer Aktion an, mit welcher die entsprechende Anwendung „gestartet“ werden kann. Mit Hilfe dieses Parameters wird ein Link erzeugt. Fehlt der Parameter, so erscheint das betroffene Plugin nicht auf der generierten Sitemap.

plugin_default_library::security_get_image()

void $YANA->handle(„security_get_image“, array $ARGS);



Argument

Typ

Default

Beschreibung

security_image_index

integer

1

Optionaler Parameter. Gibt an, an welcher Stelle der Codetabelle der Code zu finden ist, für welchen die Grafik erzeugt werden soll.

Gültige Werte sind die Ziffern 1-9

akzeptierte Argumente der Aktion „security_get_image“

Erzeugt eine Grafik im PNG-Format, welche einen zufällig erzeugten Code aus Zahlen und Buchstaben enthält. Der optionale Parameter „security_image_index“ gibt an, welche Positionsnummer dieser Code in der aktuellen Code-Tabelle hat.

Die Codetabelle verfällt in einem Zeitraum von 10 Minuten bis etwa 3 Stunden nach dem Aufruf der Funktion automatisch und wird ungültig. Wenn die Tabelle abgelaufen ist, erstellt der erneute Aufruf der Funktion eine neue Tabelle, wobei die alte ersetzt wird.

Der Aufruf der Aktion gibt keine HTML-Seite sondern eine Grafik aus. Der gültige Mime-Type ist „image/png“. Vor Ausführung der Aktion darf kein anderes Plugin eine Ausgabe erzeugt haben. Andernfalls wird die erzeugte PNG-Datei ungültig und ist nicht mehr lesbar.

Nach dem Aufruf der Aktion wird die Skriptausführung unterbrochen.

plugin_default_library::security_check_image()

boolean $YANA->handle(„security_check_image“, array $ARGS);



Argument

Typ

Default

Beschreibung

security_image_index

integer

1

Optionaler Parameter. Gibt an, an welcher Stelle der Codetabelle der Code zu finden ist, für welchen die Grafik erzeugt werden soll.

Gültige Werte sind die Ziffern 1-9

security_image

string

n/a

Erforderlicher Parameter. Text, mit dem der Inhalt der Code-Tabelle verglichen wird.

akzeptierte Argumente der Aktion „security_check_image“

Diese Aktion prüft, ob der über den Parameter „security_image“ angegebene Text mit dem Text in der Codetabelle an der Position „security_image_index“ übereinstimmt.

Gibt bei Übereinstimmung „true“ zurück, sonst „false“. Diese Aktion liefert auch dann „false“, wenn die Codetabelle nicht mehr gültig ist.

Nach Aufruf der Aktion wird die Skriptausführung fortgesetzt. Die Aktion erzeugt keine Ausgabe.

Diese Aktion dient dem Schutz des Frameworks vor unerwünschten Zugriffen durch automatische Programme, insbesondere dem Schutz vor Spam.

Fehlercodes und Meldungen

$YANA->message()

Durch Aufruf von $YANA->message($STATE, $ERR_CODE [, $REDIRECT]) kann eine Textmeldung erzeugt werden.

DIESER BEFEHL UNTERBRICHT DIE PROGAMMAUSFÜHRUNG SOFORT UND ERZWINGT EINEN OUTPUT! Gehen sie sparsam damit um.

Der Parameter $STATE gibt den Status der Meldung an. Gültige Belegungen sind:

Wert Beschreibung
OK Erfolgsmeldung
ALERT Hinweis
ERROR Fehler

akzeptierte Belegungen für Parameter $STATE

Der Parameter $ERR_CODE gibt an, welche der gültigen Meldungen angezeigt werden soll. Gültige Werte für $ERR_CODE werden in den Sprachpaketen definiert. Bspw. in der Datei "language/de/message.config". Dort können auch weitere Meldungen hinzugefügt werden.

Gültige Belegungen sind unter anderem (AUSZUG):

Code Beschreibung Textauszug
200 Erfolg Änderungen wurden gespeichert. Vielen Dank !!!
500 Allgemeiner Fehler Es ist ein Fehler aufgetreten...
403 Fehler: Zugriff verweigert Passwort erforderlich. Sie betreten einen geschützten Bereich...
UNGUELTIGE_EINGABE Fehler: Falsche Eingabe Ein gewählter Parameter ist ungültig...
404 Fehler: Datei nicht gefunden Bitte überprüfen Sie die angegebene URL und versuchen Sie es erneut.
ALLREADY_EXISTS Fehler: Eintrag doppelt Es konnte kein neuer Eintrag mit der id "%ID%" erzeugt werden, weil bereits ein anderes Eintrag mit diesem Namen existiert.
FILE_NOT_CREATED Fehler: IO-Error Die Datei "%FILE%" konnte nicht erzeugt werden.
NOT_WRITEABLE Fehler: IO-Error Der Schreibzugriff auf die Ressource "%FILE%" ist gescheitert. Daten konnten nicht gespeichert werden.
NOT_READABLE Fehler: IO-Error Der Zugriff auf die Ressource "%FILE%" ist gescheitert. Daten konnten nicht gelesen werden.

akzeptierte Belegungen für Parameter $ERR_CODE

Enthaltene Token, wie %FILE% werden ersetzt in der folgenden Weise:

$YANA->setVar('FILE', 'myFile.ext');
$YANA->message('error', 'NOT_READABLE','next_action');

$YANA->report()

Dies ist eine Alternative zu $YANA->message().

$YANA->report($REPORT) erzeugt ebenfalls eine Textmeldung, bricht das Programm jedoch nicht ab.

Das folgende Beispiel schreibt eine Meldung in die Log-Datei und erzeugt dann einen Text für die Ausgabe am Bildschirm.

$YANA->report( new log("IO-ERROR: Unable to read file $a") );
$YANA->report( new error('NOT_READABLE', array('FILE' => $a) ) );

Vergleichen Sie den Error-Code mit der Tabelle oben.

Der Parameter $REPORT ist eine Instanz einer der folgenden Klassen:

Klasse Beschreibung
log für Ausgabe in Log-Datei
message Erfolgsmeldung (Bildschirm)
warning Warnung
alert Hinweis
error Fehler

akzeptierte Typen für Parameter $REPORT

Verwendung

Der Konstruktor nimmt 2 Parameter: _construct(string $text [, mixed $data]). Der Parameter $text kann ein Error-Code sein, oder auch ein beliebiger Fließtext. Für Bildschirmausgabe sollten Error-Codes verwendet werden. Für Ausgaben in die Log-Datei bietet sich englischer Fliesstext an. Der Parameter $data ist optional und enthält weitere Optionen. Beispielsweise den Datensatz, der nicht gespeichert werden konnte, oder den Namen einer Datei, die gerade nicht geöffnet werden kann.

Das besondere an $YANA->report() ist, dass Sie damit gleichzeitig Textmeldungen in die Log-Datei schreiben UND Meldungen am Bildschirm ausgeben können. Wird die Methode mehrmals aufgerufen, werden mehrere Textmeldungen am Bidlschirm ausgegeben.

$YANA->report( new warning('FILE_NOT_CREATED', array('FILE' => $a)) );
...
$YANA->report( new alert('NOT_WRITEABLE', array('FILE' => $a)) );
...
$YANA->report( new error('500') );
$YANA->report( new log("Input/Output Error in File $a", $lost_data) );
return false;

© 2001, 2002, 2003, 2004, 2005, 2006Homepage: Thomas Meyer, www.all-community.de