Funktionen

für die Liste aller Seiten

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.

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

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.

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

The PCCF()-Funktion (PmWiki Create Callback Function) kann man einsetzen, um Callback-Funktionen zu erzeugen, die man mit preg_replace_callback einsetzt.

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() die eingelagerte Funktion übergeben.

Siehe http://php.net/create_function.

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 kein automatisches Hinzufügen von Backslashes passiert.

PPRE($search_pattern, $replacement_code, $string)

Die PPRE()-Funktion (PmWiki preg_replace evaluate) kann eingesetzt werden, um eine reguläre Ausdruckersetzung mit Auswertung durchzuführen.

Seit PHP_5.5 lehnt die preg_replace()-Funktion das /e-Flag ab 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 mit PHP_5.5):

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

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 kein automatisches Hinzufügen von Backslashes passiert.

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.

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

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 Markup-Definition neuen Stils mit Markup_e() muss PSS() NICHT im Ersetzungsstring benutzen.

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:

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($string)

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

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($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($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.

Siehe auch: Cookbook:Functions#MarkupToHTML

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 das Verzeichnis manuell anzulegen oder PmWiki genügend Rechte einzuräumen, dass es das selbst erledigen kann.

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($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.

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($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 ($pagename, 'auth level')

CondAuth implementiert das ConditionalMarkup für (:if auth level:). Zum Beispiel ist CondAuth($pagename,'edit') wahr, wenn die Autorisierungsebene 'edit' ist.

Sie können entweder Autorisierungsebenen ('read', 'edit', 'attr', 'admin') oder Aktionsnamen ('browse', 'upload', 'source') als das zweite Argument von CondAuth() einsetzen. Benutzen Sie die Funktion in Konfigurationsdateien, um Bedingungen mit einer Überprüfung der Autorisierungsebenen aufzustellen, ähnlich des Gebrauchs von (:if auth level:) in Wiki-Seiten.

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($pagename, $level, $authprompt=true, $since=0)

Pm words as said in http://article.gmane.org/gmane.comp.web.wiki.pmwiki.user/12493/match=retrieveauthpage%% mit:

   $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.)

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($pagename, $pagesection, $list=NULL, $auth='read')

RetrieveAuthSection extrahiert einen Textabschnitt aus einer Seite. Wenn $pagesection mit etwas anderem als '#' beginnt, holt sie den Text aus der Seite selbst. Andernfalls sucht RetrieveAuthSection in den Seiten, die durch $list vorgegeben sind oder in $pagename, wenn $list nicht angegeben wurde.

• Der ausgewählte Text wird in der globalen Variablen $RASPageName gespeichert.
• Der Aufrufer ist selbst verantwortlich für den Aufruf von Qualify(), wenn das nötig ist.

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($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 ReadPage($pagename); zurückgegeben wurde. 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 (also UpdatePage($pagename, '', $new);) wird alle Seitenverlaufsdaten löschen – ein tabula rasa.

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.

Categories: PmWiki Developer für die Liste aller Seiten