Tamriel-Almanach:Bot

Bots stellen gerade für den Almanach einen riesen Mehrwert da. Das haben wir mit Botmunculi und dem Waffenprojekt eindrucksvoll bewiesen. Ein Bot kann quasi alle Aufgaben übernehmen, die ein Schreiber machen kann, die keine Kreativität oder hohe Intelligenz erfordern (Wenn du sowas programmieren kannst gehts natürlich auch ;-D). Damit jeder, der mit PHP umgehen kann einen eigenen Bot programmieren kann, hat der Botmaster Death-lord bereits alles nötige programmiert, du musst nur noch deinen eigenen Einsatz programmieren.

Wenn du dich entschieden hast, einen eigenen Boteinsatz zu planen oder spezifische fragen hast sag einfach dem Botmaster Bescheid! Bei allen Fragen, die bei dir aufkommen wendest du dich bitte an mich oder die Diskussion.

Regeln

1. Jeder Bot bekommt einen eigenen Benutzer, der im Namen das Wort Bot enthält.
2. Auf der Benutzerseite muss ein Link auf diese Seite vorliegen, sowie eine kurze Erklärung was ein Bot ist und was deiner macht.
3. Die Arbeitsgeschwindigkeit darf nur unter Absprache mit Scharesoft 15 Bearbeitungen/Min. nicht überschreiten.
4. Ein Boteinsatz muss direkt vorher im IRC Chat angekündigt werden. Während des Einsatzes herrscht Anwesenheitspflicht im Chat.
5. Jeder Boteinsatz wird ebenso im den Botmaster und Scharesoft mitgeteilt werden.
6. Bei Verstoß wird dein Bot aus der Ferne unverzüglich abgeschaltet.
7. Jede Änderung vom Bot im Almanach muss, sofern möglich, einen erklärenden Kommentar beinhalten.
8. Der Quellcode sollte kommentiert sowie sauber sein und vorher von dem Botmaster genehmigt werden.
9. Jeder bearbeitete oder erstellte Artikel sollte mit der Parsing Funktion behandelt werden.

Dokumentation

Um die Dokumentation nachvollziehen zu können benötigst du die Dateien vom Botmaster.

Installation

Wichtig ist die config.php. In dieser Datei musst du die Benutzerdaten des Bots und sämtliche anderen Konfigurationsvariablen einstellen. Optionale sind als solche gekennzeichnet.

Um zu prüfen ob die Installation erfolgreich verlief, wählst du im Botmenü die Erweiterung Installation aus und startest den Vorgang, erhältst du eine Bestätigung, verlief die Installation erfolgreich (Dauert einige Sekunden). Falls nicht, kontaktiere den Botmaster oder sichte deine Logdateien.

Botmenü

Das Botmenü

Das Botmenü ist die Oberfläche des Bots. Zu dieser gelangst du über die Datei index.php. Hier siehst du einen Totmannsknopf, welcher Automatisch nach einer gewissen Zeit (Abhängig von der Geschwindigkeit) automatisch die Ausführung beendet. Durch Klick auf diesen bestätigst du deine Anwesenheit. Hierdurch wird eine ständige Aufmerksamkeit garantiert. Deine Aufmerksamkeit ist zwingend erforderlich, denn es kann immer ein unvorhersehbarer Fehler auftreten und der Bot sollte dann schnellstmöglich gestoppt werden. Mit der Geschwindigkeit kannst du kontrollieren, wie oft der Bot eine Seite bearbeiten. Diese hat Auswirkungen auf den Server des Almanachs. Unter Erweiterung wählst du die gewünschte Erweiterung aus. Nun kannst du den Vorgang starten. Im Log Fenster findest du nun sämtliche Nachrichten des Bots, diese werden auch gespeichert (vgl. Logdateien).

Den Bot erweitern

Dies gelingt sehr einfach! Jedes Mal, wenn der Bot eine Aktion ausführt, ruft er die Datei deiner Extension auf. In dieser Datei kannst du dann machen was du möchtest :-)! Die Kommunikation mit dem MediaWiki gelingt über die abstrakte Klasse core, von dieser sollte die Klasse, die du für deine Erweiterung erstellst erben. Die Datei deiner Extension wird unter dem Namen den du nach dem Schema in der config.php Datei eingegeben hast in dem Ordner Extensions gespeichert (Dateiname: EXTENSIONNAME.php; Beispiel: Erweiterung: Installation. Datei: Installation.php).

Was dein Script zurückgeben muss

Dein Script muss immer die folgende Zeile zurückgeben:

throw new Exception ( json_encode ( array ( 'STATUS', 'MELDUNG' )));

Es gibt vier verschiedene Stati:

• SUCCESS Dieser Status gibt dem Bot ein positives Feedback. Es gibt eine Erfolgs Meldung im Logfenster
• SUCCESS_STOP Dieser Status gibt dem Bot ein besonderes Feedback unzwar, die Beendigung des Einsatzes. Wird dieser Status ausgerufen, wird der Script sofort gestoppt und es gibt die Meldung "Fertig" im Logfenster.
• FAIL Hier passiert auch nichts weiter, allerdings wird eine Fehlermeldung im Logfenster gezeigt.
• FAIL_STOP Es wird ein kritischer Fehler ausgerufen, welcher den Bot sofort stoppt um schlimmeres zu verhindern oder damit der Fehler behoben werden kann ohne, dass er immer wieder auftritt.

Logdateien

Nichts ist wichtiger als einen kleinen Fehler im Nachhinein nach zu vollziehen und wieso er eigentlich aufgetreten ist. Dafür wird in vier verschiedenen Dateien (Im Logs Verzeichnis) alles geloggt:

1. Sämtliche Meldungen im Logfenster des Botmenüs (log.txt)
2. Sämtliche Fehler, die von PHP gemeldet werden (PHP_Fehler.log)
3. Sämtliche Fehler, die mit core::logError Methode geloggt wurden (PHP_Fehler_Benutzerdefiniert_Gesendete_Meldungen.log)
4. Sämtliche Rückgaben der API (Http_Kommunikation_Log.txt)

Die Funktionen des Bots und wie du sie nutzt

Datei-Upload

Dies gelingt mit der Methode upload der Klasse core.

upload ( $title, $file, $filename[, $desc = NULL[, $comment = NULL ]])

Attribute:

• $title stellt den Titel der Datei dar (Ohne Namensraum!)
• $file ist der Dateiname und Pfad ausgehend des Stammverzeichnisses der bot.php
• $filename ist der Dateiname ohne den Pfad.
• $desc die Beschreibung des Bildes (Optional: Standardwert ist der Dateititel)
• $comment der Kommentar zum Upload.

Im Fehlerfall wird false zurückgegeben, sonst die Antwort der API. Fehler werden ausführlich in den Log Dateien geloggt. Es kann unter Umständen auch zu Warnungen seitens der API kommen, wie "Die Datei existiert bereits unter einem anderen Namen", diese finden sich auch in den Log Dateien wieder und müssen überprüft werden, bevor die Datei erneut hochgeladen wird. Auch in einem solchen Fall wird false zurückgegeben.

Parsing

Das Parsing gelingt mit der Methode "parse" der "core" Klasse. Die Methode erwartet einen string und gibt ihn geparst zurück. Mit ihr wird ein Artikel den aktuellen Hilfe:Regeln und Normen automatisch angepasst.

parse ( $content)

Attribute:

• $content der Inhalt eines Artikels oder einfach nur ein Text.

Rückgabewert ist immer der geparste String. In dem unwahrscheinlichen Falle eines Fehlers wird ein false ausgegeben und in der PHP Fehler Datei geloggt.

Artikel bearbeiten

Dies geschieht mit der Methode editPage. public function editPage ( $title, $content, $minor, $comment = NULL ) Attribute:

• $title der Titel des Artikels.
• $content der Inhalt eines Artikels oder einfach nur ein Text.
• $minor Kennzeichnet bei TRUE den Artikel als kleine Bearbeitung. Sonst bitte False setzten
• $comment' Der Kommentar

Rückgabewerte Zurückgegeben wird immer im Erfolg TRUE sonst FALSE. Genaue Fehlermeldungen lassen sich in den Logs finden.

Artikel erstellen

Dies geschieht mit der Methode createPage. public function editPage ( $title, $content, $comment = NULL ) Attribute:

• $title der Titel des Artikels.
• $content der Inhalt eines Artikels oder einfach nur ein Text.
• $comment' Der Kommentar

Rückgabewerte Zurückgegeben wird immer im Erfolg TRUE sonst FALSE. Genaue Fehlermeldungen lassen sich in den Logs finden.

Artikel Inhalt abfragen

Dazu wird die Methode "getContent" der Klasse "core" genutzt. Einfach als Attribut den Seitennamen eingeben und der Inhalt wird zurückgegeben. Falls die Seite nicht existiert wird False zurückgegeben.

Logging

Falls du Sachen in eine Log Datei schreiben möchtest, bspw. welche Zeile in deiner DB ausgewählt wurde um später besser nachzuvollziehen, was schief ging, nutzt du die Methode logError ($msg) der Klasse core. Einfach als Attribut die Meldung eingeben.

Überprüfung von toten Links

Mit der Methode checkIfLinkDead ( $url ) der core Klasse wird überprüft ob ein Link tot ist. Dies wird benötigt, falls nur die URL zu einem Bild oder Artikel vorliegt und nicht der Name. Kann aber auch für Zwecke außerhalb des Almanachs verwendet werden. Im False existiert die Seite im True fall nicht.

Vorhandene Erweiterungen

dateiupload (Von Death-lord)

Hiermit wird der Upload von Massenhaften Dateien vereinfacht. Die Extension durchsucht eine Tabelle und läd die darin enthaltenen Bilder mit den angegeben Daten hoch.

Optionen

In der dateiupload.config.php Datei wird dabei der Ordner und der Tabellenname abgefragt.

weapons (Von Death-lord)

Die Extension erweitert den Almanach um Waffenartikel aus den verschiedenen Spielen.

img (Von Death-lord)

Diese Extension durchsucht den Almanach nach JPGs mit weißen Hintergründen und lädt sie ggf. als png mit transparenten Hintergrund erneut hoch.