Funktionen

für die Liste aller Seiten

Administratoren (Fortgeschritten), Entwickler

< Variablen | Dokumentations-Index | Seiten-Dateiformat >

Diese Seite erklärt einiges der inneren Arbeit von PmWiki, indem sie erklärt, wie einige der Funktionen in PmWiki arbeiten. Wegen einer kürzeren Liste/Übersicht, die zum Beispiel für Rezepteschreiber nützlich ist, siehe Cookbook:Functions.

Versichern Sie sich, dass alle relevanten internen Variablen korrekt initialisiert worden sind, wenn Sie diese Funktionen nutzen. Siehe Eigene Auszeichnungen und Eigene Aktionen wegen weiterer Informationen darüber, wie diese Funktionen typischerweise von Markup() oder $HandleActions[] aufgerufen werden.

PSFT()

PSFT($format, $timestamp=null, $locale=null, $tz=null)

Die PSFT()-Function (PmWiki String Format Time, hinzugefügt in 2.3.0) soll ein sicherer Ersatz für die sehr verbreitet benutzten PHP-Funktionen strftime() und gmtstrftime() sein, die in PHP 8.1 missbilligt werden.

Anders als strftime() akzeptiert PSFT() zwei weitere Argumente, $locale und $tz, die es erlauben, eine andere Sprache oder Zeitzone einzustellen.

PmWiki 2.3.0 benutzt diese Funktion in allen Fällen, wo es davor strftime() benutzt hatte, einschließlich des {(ftime)}-Markup-Ausdrucks. Wenn Ihre lokale Anpassung und Ihre Rezepte strftime() benutzen, sollten Sie alle Aufrufe von strftime() sicher durch PSFT() ersetzen können, ohne die Argumente zu ändern. Jeglicher Aufruf von gmtstrftime($fmt, $stamp) kann durch PSFT($fmt, $stamp, null, 'GMT') ersetzt werden.

Die alten Funktionen werden von den PHP-Entwicklern missbilligt, weil sie Inkonsistenzen auf verschiedenen Plattformen verursacht haben und abhängig von den installierten 'system locales' waren (d. h. eine Sprache funktionierte nur, wenn das System deren 'locale' installiert hatte). Die neue Funktion benutzt die PHP-Klasse IntlDateFormatter und sollte besser sein. Unglücklicherweise ist sie nicht von allen Providern aktiviert.

Eine spezielle Sprache ist also – abhängig von ihrer Installation – verfügbar mit strftime() und/oder mit IntlDateFormatter.

Außerdem verhalten sich einige selten benutzte (abkürzende) Prozent-Formate %c, %x, %X auf verschiedenen Platformen inkonsistent und der neue Formatierer könnte etwas unterschiedliche Ausgaben zeigen. Sie können jederzeit diese Abkürzungen durch die ausführlichen Formatangaben ersetzen, die die gewünschten Ausgaben erzeugen.

Aus diesem Grund ist PSFT() derzeit ein Kompromiss, der standardmäßig strftime() für PHP 8.0 oder früher weiterbenutzt. Wenn Sie ihre strftime()-Aufrufe updaten, sollten das keine Änderungen in Ihrer Ausgabe ergeben.

Sie können in der config.php-Datei die Variable $EnableFTimeNew = 1; setzen für PSFT(), um zu versuchen, IntlDateFormatter vor PHP 8.1 zu benutzen. Wenn IntlDateFormatter nicht verfügbar ist, werden die Tages- und Monatsnamen in Englisch ausgegeben. Testen Sie, was funktioniert.

Da die strftime()-Funktion missbilligt ist, ist es unwahrscheinlich, dass neue Formate hinzukommen. Wir haben zwei eigene Formate hinzugefügt:

%o für das "ordinale Suffix" des Datums wie "st" in " January 1st". Wenn IntlDateFormatter nicht verfügbar ist, wird der Suffix in Englisch angezeigt.
%L für einen von Menschen lesbaren Zeitstempel des Formats @2022-09-25T11:49:08Z, das formatiert angezeigt wird entweder aös $TimeFmt oder in der lokalen Zeitzone des Besuchers, siehe $EnableLocalTimes.

Ein Unterschied zwischen strftime($format, $stamp) und PSFT($format, $stamp) ist, wie sie ein falsches, leeres oder nicht-numerisches $stamp-Argument behandeln.

`$stamp` argument	`strftime($format, $stamp)`	`PSFT($format, $stamp)`
numeric	the stamp	the stamp
missing or null	current time	current time
false	1970-01-01	current time
"" (empty string) other non-numeric	1970-01-01 or false (older PHP versions) Warning: TypeError (PHP 7.4+)	current time

Für PmWiki scheint es vernünftig zu sein, leere Strings und andere nicht-numerische Werte als die aktuelle Zeit zu behandeln. Wenn Ihre stamp-Variable leer oder false sein könnte, und ihr Rezept verlässt sich darauf, dass strftime() "1970-01-01" zurück liefert, sollten Sie den Zeitstempel in eine Ganzzahl umwandeln:

  PSFT($format, intval($stamp));

pmtoken()

pmtoken($check = 0, $abort = false)

Die pmtoken()-Funktion setzt oder prüft einen einmaligen Session-Identifier für den Gebrauch in Eingabeformularen mit dem Ziel, 'cross-site request forgeries' (etwa Website-übergreifende Anfragenfälschung, CSRF) zu verhindern.

Der Aufruf von pmtoken() oder pmtoken(0) erzeugt ein Token, wenn das nicht existiert, speichert es im $_SESSION-Array und gibt es zurück. Er setzt außerdem die Variablen $FmtV['$TokenValue'], die man in HTML-Vorlagen benutzen kann, und $InputValues['pmtoken'], die man in Markup-Formularen (Formulare) benutzen kann, obwohl es einfacher sein kann, stattdessen (:input pmtoken:) zu benutzen.

Der Name des Input-Elements, standardmäßig 'pmtoken', kann verändert werden durch zum Beispiel das Setzen von $FmtV['$TokenName'] = 'CSRFtoken';.

Der Aufruf von pmtoken(1) prüft den $_POST['pmtoken']-Wert und gibt wahr zurück, wenn er gültig ist.

Der Aufruf von pmtoken(2) prüft den $_GET['pmtoken']-Wert und gibt wahr zurück, wenn er gültig ist.

Der Aufruf von pmtoken(1, true) or pmtoken(2, true) mit einem zweiten wahren Argument und einem ungültigen Token wird direkt Abort() aufrufen und enden.

pmcrypt()

pmcrypt($password, $salt = null)

Die pmcrypt()-Funktion ist dazu gedacht, einen sicheren Ersatz für die PHP 5.6+ crypt()-Funktion zu bieten, wenn man kein $salt einsetzt, was sonst eine Warnmeldung (notice) hervorrufen würde. Wenn ein $salt angegeben wird, wird crypt() aufgerufen, um ein existierendes Passwort zu prüfen. Wenn ein $salt nicht angegeben wird, wird password_hash() aufgerufen, um ein kryptografisch starkes Passwort zu erzeugen.

pmsetcookie()

pmsetcookie($name, $val="", $exp=0, $path="", $dom="", $secure=null, $httponly=null)

Diese Funktion ist gedacht als Ersatz für setcookie(). Sie setzt die $secure- und $httponly-Argumente, wenn sie nicht von der aufrufenden Funktion gesetzt werden und wenn $EnableCookieSecure und $EnableCookieHTTPOnly aktiviert sind.

PCCF() Missbilligt seit PHP 7.2

PCCF($php_code, $callback_template='default', $callback_arguments = '$m')

Die PCCF()-Funktion (PmWiki Create Callback Function) kann man einsetzen, um Callback-Funktionen zu erzeugen, die man mit preg_replace_callback einsetzt. Sie ist nötig für PHP 5.5., funktioniert aber auch bei früheren Versionen.

Das erste Element ist der auszuwertende PHP-Kode.

Das zweite Element (optional) ist die Callback-Vorlage, ein Schlüssel aus dem globalen $CallbackFnTemplates-Array. Es gibt zwei Vorlagen, die Rezepte-Autoren nutzen können

'default' übergibt den $php_code als einen Funktionskode
'return' packt $php_code als "return $php_code;" ein (seit PmWiki 2.2.62)

Das dritte Argument (optional) ist das Argument der Callback-Funktion. Beachten Sie, dass PmWiki das '$m'-Argument heranzieht, um Übereinstimmungen mit regulären Ausdrücken zu übergeben, Ihre Funktion kann aber auch eigene Argumente benutzen.

PCCF() erzeugt eine anonyme (Lambda-)Funktion, die den übergebenen Kode enthält, und lagert sie in einem Cache ein. Bei darauffolgenden Aufrufen mit demselben $php_code wird PCCF() den eingelagerten Funktionsnamen zurückgeben.

Siehe PHP create-function.

PHP 7.2 missbilligt create_function() und zukünftige Versionen werden die Funktion entfernen. Wenn Sie alten Kode übertragen müssen, der PCCF() benutzt hat, können Sie gewöhnlich reguläre Funktionen schreiben und den Funktionsnamen dort übergeben, wo Sie vorher das Ergebnis von PCCF() übergeben haben. Nehmen wir z. B. an, Sie haben ein Muster wie dieses:

'/(?<=^| )([a-z])/' => PCCF("return strtoupper(\$m[1]);"),

Für PHP_7.2-Kompatibilität können Sie eine Callback-Funktion schreiben:

function my_callback($m) { return strtoupper($m[1]); }

Verändern Sie dann noch das Muster, dass es so aussieht:

'/(?<=^| )([a-z])/' => 'my_callback',

Siehe auch: das Rezept PccfToPcfOverride erlaubt existierende Rezepte unter PHP 7 laufen zu lassen ohne "deprecated create_function()"-Meldungen zu verursachen.

PPRA()

PPRA($array_search_replace, $string)

Die PPRA()-Funktion (PmWiki preg_replace array) kann man einsetzen, um eine Ersetzung mit Hilfe eines regulären Ausdrucks mit oder ohne Auswertung durchzuführen, für PHP_5.5-Kompatibilität.

Seit PmWiki 2.2.56 nutzt PmWiki diese Funktion, um die folgenden Arrays abzuarbeiten: $MakePageNamePatterns, $FmtP, $QualifyPatterns, $ROEPatterns, $ROSPatterns, $SaveAttrPatterns, $MakeUploadNamePatterns. Alle Benutzereinstellungen sollten weiterhin mit PHP_5.4 und früher funktionieren, aber Wikis, die mit PHP_5.5 laufen, brauchen ein paar Änderungen.

Das erste Argument enthält die "suchen'=>'ersetzen'-Paare, das zweite ist der "haystack"-String, der manipuliert werden soll.

Die 'replace'-Teile des Arrays können Strings oder Funktionsnamen sein. Wenn der 'replace'-Teil ein aufrufbarer Funktionsname ist, wird er via preg_replace_callback() mit dem Array der Übereinstimmungen als erstes Argument aufgerufen. Wenn er keine Funktion ist, wird ein einfacher preg_replace()-Aufruf durchgeführt.

Früher hat PmWiki solche Konstrukte benutzt:

$fmt = preg_replace(array_keys($FmtP), array_values($FmtP), $fmt);

Jetzt ist es möglich, einfach dies zu benutzen:

$fmt = PPRA($FmtP, $fmt);

Beachten Sie, dass die Suchmuster seit PHP_5.5 kein /e-Flag (Evaluation, Auswertung) mehr haben können. Beim Erzeugen eines $array_search_replace-Arrays vor PHP_5.5 konnte man (z. B. für $MakePageNamePatterns) etwas einsetzen wie:

'/(?<=^| )([a-z])/e' => "strtoupper('$1')",

Seit PHP_5.5 sollte man dies einsetzen (funktioniert auch mit PHP_5.4 und früher):

'/(?<=^| )([a-z])/' => PCCF("return strtoupper(\$m[1]);"),

Beachten Sie, dass das /e-Flag jetzt weggelassen werden sollte, anstelle von '$0', '$1', '$2', sollte man $m[0], $m[1], $m[2], etc. in dem Ersetzungskode einsetzen, und der Aufruf von PSS() im Ersetzungskode ist nicht nötig, da Backslashes nicht automatisch hinzugefügt werden.

Anstatt PCCF() zu benutzen, haben wir für PHP 7.2 and jünger eine reale Funktion in unser Add-On hinzugefügt, und übergeben ihr den Funktionsnamen als Musterersetzung (siehe Beispiel unter PCCF, das auch unter PHP 4 und 5 funktioniert):

'/(?<=^| )([a-z])/' => 'my_callback',

PPRE() missbilligt seit PHP 7.2

PPRE($search_pattern, $replacement_code, $string)

Die PPRE()-Funktion (PmWiki preg_replace evaluate) kann eingesetzt werden, um eine Ersetzung eines regulären Ausdrucks mit Auswertung durchzuführen.

Seit PHP_5.5 missbilligt die preg_replace(-Funktion das /e-Evaluations-Flag und zeigt Warnungen an, wenn es doch eingesetzt wird. Die PPRE()-Funktion erzeugt automatisch eine Callback-Funktion mit dem Ersetzungskode und ruft diese auf.

Vor PHP_5.5 konnte man solche Aufrufe nutzen:

$fmt = preg_replace('/\\$([A-Z]\\w*Fmt)\\b/e','$GLOBALS["$1"]',$fmt);

Seit PHP_5.5 kann man den vorhergehenden Kode-Schnipsel durch den folgenden ersetzen (funktioniert auch vor PHP 5.5):

$fmt = PPRE('/\\$([A-Z]\\w*Fmt)\\b/','$GLOBALS[$m[1]]',$fmt);

In PHP 7.2 und jünger ruft der Aufruf dieser Funktion eine "deprecated"-Notiz hervor. Sie sollten Ihren Kode neu schreiben für den Aufruf der Funktion preg_replace_callback, indem Sie den Kode in eine richtige Funktion übertragen:

$fmt = preg_replace_callback('/\\$([A-Z]\\w*Fmt)\\b/ ', 'my_global_var_callback',$fmt);

function my_global_var_callback($m) { return $GLOBALS[$m[1]]; }

Anstatt PCCF() zu benutzen, um eine anonyme Funktion zu erzeugen, fügen wir unserem Add-on eine reale Funktion hinzu und übergeben dann den Funktionsnamen als Muster-Ersetzung (siehe Beispiel bei PCCF, das funktioniert auch mit PHP4 und 5):

'/(?<=^| )([a-z])/' => 'my_callback',

Qualify()

Qualify($pagename, $text)

Qualify( setzt $QualifyPatterns ein, um relative Verweise und Referenzen in absolute Entsprechungen umzuwandeln. Diese Funktion wird von gewöhnlichen Markups aufgerufen, die Text aus anderen Seiten einfügen. Sie ersetzt Links wie [[Page]] durch [[Group/Page]] und Seiten(text)variablen wie {$Title} durch {Group.Page$Title}, sodass sie in der Quellenseite und der einbettenden Seite gleichermaßen funktionieren. Siehe auch $QualifyPatterns und RetrieveAuthSection().

PHSC()

PHSC($string_or_array, $flags=ENT_COMPAT, $encoding=null, $double_encode=true)

Die PHSC()-Funktion (PmWiki HTML special characters) ist ein Ersatz für die PHP-Funktion htmlspecialchars.

Die htmlspecialchars()-Funktion wurde ab PHP_5.4 in zweierlei Hinsicht verändert: sie benötigt nun einen gültigen String für die eingesetzte Zeichenkodierung und die voreingestellte Zeichenkodierung ist UTF-8. Dadurch können Abschnitte einer Seite auf vielen Sites, die ISO-8859-1 nutzen, leer sein, wenn das dritte Argument ($encoding) in htmlspecialchars() bei dessen Aufruf nicht gesetzt ist.

Die PHSC()-Funktion ruft htmlspecialchars() mit einer 8-bit-Zeichenkodierung als drittes Argument auf, welche Zeichenkodierung das Wiki auch immer hat (es sei denn, Sie setzen explizit eine Zeichenkodierung). Auf diese Weise enthält der String niemals ungültige Zeichen.

Es sollte für Entwickler sicher sein, wenn sie Aufrufe von htmlspecialchars() durch solche von PHSC() ersetzten. In PHSC() ist nur der erste Parameter obligatorisch, wenngleich Autoren dazu neigen könnten, PHSC($string_or_array, ENT_QUOTES) aufzurufen.

Anders als htmlspecialchars() kann die PHSC()-Funktion Arrays iterativ bearbeiten, dabei werden nur die Werte verändert, nicht die Schlüssel des Arrays.

PSS()

PSS($string)

Die PSS()-Funktion (PmWiki Strip Slashes) entfernt die Backslashes, die automatisch durch die /e-Option von PHPs preg_replace()-Funktion vor Anführungszeichen gesetzt werden. PSS() wird am ehesten eingesetzt, um Argumente für Markup() zu ersetzen, wenn das Muster die /e-Option gesetzt hat und eines oder mehrere der eingeklammerten Musterteile Backslashes oder Anführungszeichen enthalten könnte.

Von PM: PmWiki erwartet den Einsatz von PSS() immer innerhalb von Strings in doppelten Anführungszeichen, in deren Inneren wiederum einfach angeführte Strings enthalten sind. Der Grund dafür ist, dass wir nicht wollen, dass $1 oder $2 aus Versehen Zeichen enthalten, die dann zwischen den doppelten Anführungzeichen interpretiert werden, wenn PSS() durchgeführt wird.

Markup('foo', 'inline', '/(something)/e', 'Foo(PSS("$1"))'); # falsch

Markup('foo', 'inline', '/(something)/e', "Foo(PSS('$1'))"); # richtig

Beachten Sie, die Extra-Schrägstriche werden nur von preg_replace() mit einem /e-Modifizierer hinzugefügt. Die Markup-Definition mit Markup_e() braucht PSS() im Ersetzungsstring NICHT zu benutzen. Die Markup-Definitionen neuen Typs mit Markup() und einem einfachen Funktionsnamen als Ersetzung brauchen PSS() in der Ersetzungsfunktion NICHT zu benutzen. Löschen Sie die PSS()-Aufrufe, wenn Sie alte Markup-Regeln in das neue Format übertragen.

Beispiel

Dies ist ein fiktives Beispiel, bei dem PSS() eingesetzt werden sollte. Nehmen wir an, dass Sie eine Direktive (:example:) definieren wollen, sodass (:example "Ein Pferd":) diesen HTML-Kode ergibt:

<div>"Ein Pferd"</div>.

Und so könnte die Markup-Regel erzeugt werden:

Markup('example', 'directives',
       '/\\(:example\\s(.*?):\\)/e',
       "Keep('<div>'.PSS('$1').'</div>')");

Der Einsatz von PSS() um '$1' ist nötig, weil der auf das Muster passende Text Anführungszeichen enthalten könnte und das /e Backslashes davorsetzen wird.

stripmagic()

stripmagic($string)

Diese Funktion sollte eingesetzt werden beim Bearbeiten des Inhalts von $_POST- oder $_GET-Variablen, wenn diese Anführungszeichen oder Backslashes enthalten könnten. Sie prüft get_magic_quotes() und entfernt, beim Ergebnis wahr, die automatisch eingefügten Escapes aus dem String.

Diese Funktion kann Arrays rekursiv bearbeiten (nur die Werte werden bearbeitet).

FmtPageName()

FmtPageName($fmt, $pagename)

Gibt $fmt zurück, mit durchgeführter $variablen- und $[Internationalisierungs]-Ersetzung, mit der Vorgabe, dass die aktuelle Seite $pagename ist. Siehe unter den Variablen nach einer (unvollständigen) Liste der verfügbaren Variablen, siehe auch nach in Internationalisierungen wegen der Internationalisierung. Sicherheit: Nicht anwenden bei vom Benutzer eingegebenen Daten.

Das ist eine der wichtigsten Funktionen in PmWiki, siehe in FmtPageName() wegen der vielen Details.

Markup()

Markup($name, $when, $pattern, $replace)

Fügt der Umwandlungstabelle ein neues Markup hinzu. Eine detailliertere Beschreibung finden Sie in Eigene Auszeichnungen.

Diese Funktion wird verwendet, um Übersetzungsregeln in PmWikis Übersetzungs-'Maschine' einzufügen. Alle Argumente von Markup() sind Strings, und zwar

$name: Der String benennt die eingefügte Regel. Wenn es schon eine Regel mit diesem Namen gibt, wird diese Regel ignoriert.
$when: Dieser String wird genutzt, um zu kontrollieren, wann eine Regel angewandt wird relativ zu anderen Regeln. Die Angabe "<xyz" bedeutet, wende diese Regel vor der Regel namens "xyz" an, während ">xyz" bedeutet, wende diese Regel nach der Regel namens "xyz" an. Siehe Eigene Auszeichnungen wegen weiterer Details bezüglich der Reihenfolge von Regeln.
$pattern: Dieser String ist ein regulärer Ausdruck, der von der Übersetzungs-'Maschine' benutzt wird, um nach dem Auftreten dieser Regel in der Quelle für das Markup zu suchen.
$replace: Dieser String wird den auf den regulären Ausdruck passenden Text ersetzen, wenn einer gefunden wurde.

Siehe auch Eigene Auszeichnungen und Cookbook:Functions#Markup

MarkupToHTML()

MarkupToHTML($pagename, $str)

wandelt den String in $str, der das Markup enthält, in den korrespondierenden HTML-Kode um, unter der Vorgabe, die aktuelle Seite sei $pagename. MarkupToHTML ersetzt als erstes \n\n Sequenzen durch <:vspace>, wenn ihm Text übergeben wird. Nach und nach wird <:vspace> durch die Markup-Regeln behandelt:

'!vspace' entfernt <:vspace> hinter Überschriften.

'<vspace><p>' ersetzt<:vspace><p> durch <p class='vspace'>

'<vspace>' ersetzt <:vspace> durch <div class='vspace'>

und schließlich

'^<:' entfern alle verbliebenen <:vspace>, meist von wiederhergestelltem [=escaped text=].

Siehe auch: Cookbook:Functions#MarkupToHTML

mkdirp()

mkdirp($dir)

Die Funktion mkdirp($dir) legt ein Verzeichnis $dir an, wenn es nicht schon existiert, einschließlich aller Elternverzeichnisse, die nötig sind. Für jedes erzeugte Verzeichnis wird geprüft, ob die Rechte für dies Verzeichnis ausreichen, damit PmWiki-Skripten daraus lesen und darin schreiben dürfen. Das schließt den Test auf Einschränkungen ein, die PHPs 'safe_mode'-Einstellungen bewirken. Wenn es mkdirp() nicht möglich ist, erfolgreich ein Schreib-/Lese-Verzeichnis anzulegen, bricht mkdirp() mit einer Fehlermeldung ab, die dem Administrator die Schritte anzeigt, entweder $dir manuell anzulegen oder PmWiki genügend Rechte einzuräumen, dass es das selbst erledigen kann.

Lock()

Lock(0)

Diese Funktion wird benutzt, um sicherzustellen, dass nur eine Instanz von PmWiki läuft, wenn Dateien geschrieben werden. Sie sperrt nicht Dateien für das Bearbeiten.

Benutzen Sie in einem Rezept:

Lock(2); um ein exklusives Sperren zu erreichen, sodass kein anderer PHP-Prozess Dateien verändern kann. Das kann benutzt werden, wenn Ihre Funktion Dateien auf den Server schreibt.
Lock(1); um ein geteiltes (shared) Sperren zu erreichen. Das kann eingesetzt werden, wenn Ihre Funktion Dateien auf dem Server liest, im Falle, dass ein anderer Prozess Schreiboperation daran vornimmt.
Lock(0); um ein voriges exklusives oder geteiltes Sperren freizugeben. Benutzen Sie das unmittelbar nachdem Ihre Funktion die Lese- oder Schreiboperation abgeschlossen hat.

Wenn Sie ein erlangtes Sperren nicht freigeben, sollte es automatisch am Ende des Prozesses freigegeben werden.

MakeLink()

MakeLink($pagename, $target, $txt, $suffix, $fmt)

Die Funktion MakeLink($pagename, $target, $txt, $suffix, $fmt) gibt einen HTML-formatierten Anker-Verweis zurück. Ihre Argumente sind wie folgt:

 $pagename ist die Quellseite
 $target ist das Ziel des Verweises
 $txt ist der Wert für '$LinkText' in der Ausgabe 
 $suffix ist ein Anhängsel, das an $txt angehängt wird 
 $fmt ist ein Formatstring, der zur Anwendung kommt

Wenn $txt NULL ist oder nicht angegeben ist, dann wird es automatisch aus $target bestimmt.

Wenn $fmt NULL ist oder nicht angegeben ist, dann verwendet MakeLink das Standardformat, das durch den Typ des Verweises gegeben ist. Für Seitenverweise sind das die $LinkPageExistsFmt und die $LinkPageCreateFmt-Variablen, für externe Verweise kommt es entweder vom $IMapLinkFmt-Array oder von $UrlLinkFmt. Innerhalb des Formatstrings wird $LinkUrl ersetzt durch den aufgelösten URL für den Verweis, $LinkText wird ersetzt durch den zugehörigen Text und $LinkAlt wird ersetzt durch alle "title"-Informationen (alternativer Text), die mit dem Verweise zusammenhängen.

Siehe auch: MakeLink und Cookbook:Functions#MakeLink

MakeUploadName()

MakeUploadName($pagename, $x)

MakeUploadName() nimmt einfach einen String $x (den Namen eines Anhangs) und wandelt ihn in einen gültigen Namen um, indem alle unerwünschten Zeichen entfernt werden. Der Name soll mit einem alphanumerischen Zeichen beginnen und enden. Seit Version 2.0.beta28, wird die Dateierweiterung in Kleinbuchstaben umgewandelt. Diese Funktion ist in scripts/upload.php definiert und wird nur angewendet, wenn Hochladen von Dateien aktiviert ist.

`DownloadUrl($pagename, $path)`

Diese Funktion gibt den öffentlichen URL einer angehängten Datei zurück. Die Argumente sind die Folgenden:

$pagename - die aktuell bearbeitete Seite
$path - der Dateipfad, wie in file.ext, Otherpage.ext oder Group/OtherPage/file.ext

Wenn die Datei nicht existiert, gibt die Funktion false zurück. Die globale Variable $FmtV['$LinkUpload'] enthält den URL zum Hochladen-Formular für eine Datei mit einem solchen Namen zum Anhängen. Die globale Variable $FmtV['$LinkDownload'] enthält den URL zur Datei, als sei sie bereits hochgeladen.

Die Funktion ruft MakeUploadName() mit dem $path-Argument auf, also brauchen Sie das nicht selbst tun, bevor Sie die Funktion aufrufen.

Der zurückgegebene URL berücksichtigt $UploadPrefixFmt und $EnableDirectDownload des Wikis.

SessionAuth()

SessionAuth($pagename, $auth=NULL)

SessionAuth() bewältigt die Aufrechterhaltung der Authentifikation mit Cookie-Sitzungen. Die Sitzung enthält ein Passwort oder eine überprüfte ID und verbundene Gruppen von vorherigen Aufrufen. Es fügt der Sitzung Elemente, die von $auth übergeben werden, hinzu. Sie schreibt außerdem jedes Element, das in der Sitzung gesichert wurde, in $AuthPw (Passwörter) und $AuthList (IDs und Gruppen).

IsAuthorized()

IsAuthorized($chal, $source, &$from)

IsAuthorized() nimmt einen Seitenattribute-String (z. B. "id:user1 $1$Ff3w34HASH...") in $chal entgegen.

$source wird einfach zurückgegeben und wird gebraucht, um die Auth-Kaskade (Seitenattribute - Gruppenattribute - $DefaultPassword) aufzustellen.

$from wird zurückgegeben, wenn $chal leer ist, weil es nicht vor dem Aufruf von IsAuthorized() überprüft wird. Das ist nötig für die Auth-Kaskade. IsAuthorized() gibt ein Array mit drei Werten zurück: $auth 1 - authenticated, 0 - not authenticated, -1 - refused; $passwd; $source von der Parameterliste.

CondAuth()

CondAuth($pagename, 'auth level')

CondAuth() implementiert das ConditionalMarkup für (:if auth level:). Zum Beispiel ist CondAuth($pagename,'edit') wahr, wenn die Autorisierungsebene 'edit' ist. Benutzen Sie die Funktion in lokalen Konfigurationsdateien,um Bedingungen mit einer Überprüfung der Autorisierungsebenen aufzustellen, ähnlich des Gebrauchs von (:if auth level:) in Wiki-Seiten.

Sie können entweder Autorisierungsebenen ('read', 'edit', 'attr', 'admin') oder Aktionsnamen ('browse', 'upload', 'source') als das zweite Argument von CondAuth() einsetzen.

Anmerkung: CondAuth() sollte aufgerufen werden, nachdem alle Autorisierungssebenen und Passwörter definiert worden sind. Wenn Sie sie mit PmWikiDe.Drafts benutzen, sollten Sie das draft.php-Skript einfügen bevor sie CondAuth() aufrufen:

   $EnableDrafts = 1;
   $DefaultPasswords['publish'] = pmcrypt('secret');
   include_once("$FarmD/scripts/draft.php");
   if (! CondAuth($pagename, 'edit')) { /* was auch immer */ }

Es ist wichtig, sich zu erinnern, dass der beste Platz für den Aufruf von CondAuth() nahe dem Ende Ihres config.php-Skriptes ist. CondAuth() bevölkert den Cache (die Cashes), nachfolgende (Kochbuch-)Skripten könnten damit Schwierigkeiten haben, weil sie einen leeren Cache erwarten. Troubleshooting ist in einem solchen Fall eine schwierige Angelegenheit.

RetrieveAuthPage()

RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0)

Vergleichen Sie Pms Worte in https://www.pmwiki.org/pipermail/pmwiki-users/2005-April/012804.html, wobei:

   $pagename   - Name der zu lesenden Seite
   $level      - erforderliche Autorisierungsebene (read/edit/auth/upload)
   $authprompt - wahr, wenn der Benutzer nötigenfalls zur Eingabe des Passwortes 
                 aufgefordert werden sollte
   $since      - wieviel vom Seitenverlauf gelesen werden soll 
                 0 == lies die komplette Seite einschließlich der ganzen Versionen ein
                 READPAGE_CURRENT == lies die Seite ein ohne die Versionen zu laden
                 timestamp == lies die Versionen nur zurück bis zum Zeitstempel ein

Der $since-Parameter erlaubt PmWiki, das Einlesen zu beenden, sobald es die benötigte Information hat – d. h., wenn eine Operation wie Browsen die Seitenversionen nicht braucht, kann die Angabe von READPAGE_CURRENT die Ladezeit merklich verkürzen. (Das kann insbesondere für so etwas wie Suchen und Seitenlisten wichtig sein.) Jedenfalls wird bei Kombination mit UpdatePage() die upgedatete Seite keine Versionen enthalten.

Wenden Sie zum Beispiel $page = @RetrieveAuthPage('Main.MyPage', 'read') an, um ein Seitenobjekt zu erhalten, das all die Informationen der korrespondierenden Datei in unterschiedlichen Schlüsseln enthält, $page['text'] beispielsweise enthält einen String mit dem aktuellen Inhalt (wiki markup) von Main.MyPage. Dieser Gebrauch ist der alternativen Funktion ReadPage($pagename, $since=0) vorzuziehen, da sie die Autorisierung des Benutzers berücksichtigt, d. h. sie überprüft die Autorisierungsebene vorm Laden der Seite, jedenfalls kann sie so eingestellt werden. ReadPage() liest eine Seite ohne Rücksicht auf die Rechte ein.

Übergibt man 'ALWAYS' als Autorisierungsebene (statt 'read', 'edit', etc.), veranlasst das RetrieveAuthPage(), die Seite auf jeden Fall zu lesen, sogar, wenn sie mit einem Lesepasswort geschützt ist.

RetrieveAuthSection()

RetrieveAuthSection($pagename, $pagesection, $list=NULL, $auth='read')

RetrieveAuthSection() extrahiert einen Textabschnitt aus einer Seite. Wenn $pagesection mit etwas anderem als '#' beginnt, wird der Teil vor dem ersten '#' – oder bei dessen Fehlen, der gesamte Text – als Angabe der gewünschten Herkunftsseite angesehen. Andernfalls sucht RetrieveAuthSection(), sofern $list angegeben wurde, in den darin genannten Seiten (sollte ein Array sein). Falls keine dieser beiden Möglichkeiten eine Quellseite vorgegeben hat, wird $pagename als Quelle verwendet.

Der Name der verwendeten Quellseite wird in der globalen Variablen $RASPageName gespeichert.
Die aufrufende Funktion ist selbst verantwortlich dafür, ob und wie der beschaffte Text mittels Qualify() aufbereitet werden muss. Dies ist (nur) dann nötig, wenn Sie vorausbestimmen möchten, wie unqualifizierte Seiten- und Variablennamen aufgelöst werden sollen.
- Wenn sie so funktionieren sollen wie im Originaltext, wählen Sie die Quellseite als Bezugsseite für Qualify().
- Wenn der importierte Text nicht als Wikitext gedacht ist, sondern als sonstige Auszeichnungssprache, in der Doppelpaare eckiger Klammern vorkommen können, oder Dollarzeichen in geschweiften Klammern, dann sollte der Text nicht mittels Qualify() angepasst werden. Wenn Sie den Text in einen Wikitext ausgeben wollen, müssen Sie ihn möglicherweise mittels Keep() als "endgültig" verpacken lassen (im Falle von HTML-, RSS- oder sonstig XML-artiger Ausgabe: vorher PHSC()!), damit nachgelagerte Verarbeitungsschritte nicht auf die Idee kommen, sie müssten eine scheinbar vergessene Qualify()zierung nachholen.
- Wenn Ihr Kode Wikitext für eine Hilfsseite produziert, die von anderen Seiten in einem späteren Stadium der Einfügungskette einverleibt wird, benutzen Sie "GruppenName.SeitenName" der Hilfsseite als $pagename-Argument für Qualify().

Das bietet einen Weg, das von ReadPage zurückgegebene Array zu begrenzen, sodass es nur den Inhalt bis zu einer bestimmten Abschnittmarkierung herauszieht. Zum Beispiel, ziehe den Text zwischen dem Textbeginn und '##blogend' heraus:

function FeedText($pagename, &$page, $tag) {
  $text = RetrieveAuthSection($pagename, '##blogend');
  $content = MarkupToHTML($pagename, $text);
  return "<$tag><![CDATA[$content]]></$tag>";
}

Das '##blogend'-Argument heißt, lies vom Beginn der Seite bis genau vor der Zeile, die die Markierung enthält. Siehe Einbinden anderer Seiten wegen weiterer Informationen über die Abschnittspezifikationen.

Diese Version liest keinen Text von Seiten, die lesegeschützt sind; wenn Sie Text auch von lesegeschützten Seiten haben wollen:

  $text = RetrieveAuthSection($pagename, '##blogend', NULL, 'ALWAYS');

UpdatePage()

UpdatePage($pagename, $old (page object), $new (page object));

weitere technische Anmerkungen

UpdatePage() erlaubt Kochbuchrezepten, das Verhalten des Bearbeitens einer Wikiseite mit dem Browser zu imitieren. Intern macht PmWiki einige haushälterische Arbeiten, die über diese Funktion erreichbar sind (Erhalten der Verlaufs-(diff)-Information, Erhöhen der Seitenrevisionsnummer, Auffrischen der RecentChanges-Seiten, Senden von E-Mail-Benachrichtigungen etc. )

"Page objekt" bezieht sich auf ein Array, das von RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0); (vorzugsweise) zurückgegeben wurde oder von ReadPage($pagename); (berücksichtigt keine Seitensicherheit). Anmerkung: $new['text'] sollte alle Seitendaten für die neue Version der Seite enthalten.
Wenn eine Seite nicht existiert, wird UpdatePage() versuchen, sie anzulegen.
Weglassen von $old (z. B. UpdatePage($pagename, '', $new);) wird alle Seitenverlaufsdaten löschen – ein tabula rasa.
- Wenn Sie $old erhalten durch die Benutzung von RetrieveAuthPage($pagename,$auth,$prompt,READPAGE_CURRENT) und $new=$old setzen, wird UpdatePage() auch alle früheren Versionen löschen.

UpdatePage() kann nicht direkt von config.php aufgerufen werden, weil es notwendige Initialisierungen gibt, die erst später in pmwiki.php gemacht werden. Es reicht nicht, stdconfig.php zu laden. Wenn Sie UpdatePage() nutzen wollen, müssen Sie es innerhalb einer eigenen Auszeichnung, eines eigenen Markup-Ausdrucks, oder einer benutzerdefinierten Aktion tun.

InsertEditFunction()

InsertEditFunction($newfn, $where='<PostPage')

Diese Funktion macht es Rezeptautoren einfach, eine eigene Funktion in einer bestimmten Position des Prozesses einzufügen, siehe $EditFunctions und UpdatePage().

Das erste Argument ist der Name der neuen Funktion.

Das zweite Argument ist die Position, an der die neue Funktion eingefügt werden soll, relativ zu anderen Bearbeitenfunktionen (edit functions). Das kann sein:

"<" am Beginn, vor der ersten Bearbeitenfunktion
">" am Ende, nach der letzten Bearbeitenfunktion
"<ExistingEditFunction" vor einer angegebenen Bearbeitenfunktionen
">ExistingEditFunction" nach einer angegebenen Bearbeitenfunktionen

Die Funktion gibt bei Erfolg true zurück, beim Scheitern wird false zurückgegeben (wenn die angegebenen Funktion nicht existiert oder nicht erkannt wird)

DisableSkinParts()

DisableSkinParts('parts to disable');

Diese Funktion erlaubt, die Abschnitte des Skins, alsda sind 'header', 'footer', 'title', 'actions', und 'sidebar' zu deaktivieren wie mit den korrespondierenden Direktiven (:notitle:) (:noleft:) etc. In Ihrer Funktion benutzen sie dann so etwas wie:

  DisableSkinParts('Left Header Footer Action Title');

ParseArgs()

Siehe Cookbook:ParseArgs.

Redirect()

PageIndexTerms()

AsSpacedUTF8(), AsSpaced()

AsSpaced() ist in pmwiki.php deklariert.
AsSpaced() konvertiert eine Zeichenkette mit Wikiwörtern in eine Version der Zeichenkette mit Leerzeichen. Die Funktion kann via $AsSpacedFunction überschrieben werden, wie es in AsSpacedUTF8() gemacht wird.
AsSpacedUTF8() ist im xlpage-utf-8.php-Skript deklariert.

Siehe auch

Cookbook.Functions ? auf englisch

Kategorien: PmWiki Developer für die Liste aller Seiten

< Variablen | Dokumentations-Index | Seiten-Dateiformat >

Übersetzung von PmWiki.Functions, Originalseite auf PmWikiDe.Functions — Backlinks

Zuletzt geändert:	PmWikiDe.Functions	am 20.05.2023
	PmWiki.Functions	am 19.05.2023