build-a-bot.php

build-a-bot.php ist ein minimales Framework zum Schreiben von Mastodon-Bots in php. Die Implementierung der Mastodon API beschränkt sich dabei im Wesentlichen auf das Posten von Status-Nachrichten.

Enthalten ist eine Sammlung von Beispiel-Bots, die einfache Aufgaben illustrieren.

Einen eigenen Bot schreiben

Du kannst dieses Repository kopieren (z.B. als Fork oder Klon), die Konfiguration anpassen und eins der Beispiele anpassen. Herzstück sind die Klasse inc/nesges/class.Mastodon.php die die Mastodon-API implementiert (in sehr begrenztem Umfang!) und die Funktionssammlung inc/functions.php die einfache Implementierung zum Abrufen von Daten aus entfernten Quellen bereit hält.

Ziel ist explizit nicht ein vollständiges Framework zur Bot-Entwicklung bereit zu stellen, sondern einen Punkt von dem aus du starten kannst, um mit der wirklichen Arbeit zu beginnen. Die Erfahrung zeigt aber, dass sehr viele Bot-Ideen nicht viel mehr brauchen, als das was hier bereits implementiert ist.

Konfiguration

Kopiere die Datei config.sample.php zu config.php und passe mindestens die Schlüssel name, mastodon.domain und mastodon.token an.

debug

Ist debug = true posten die Beispielbots nicht, sondern geben den Text auf STDOUT aus.

name

name wird als User-Agent-Header verwendet und muss nicht dem Usernamen des zugehörigen Accounts entsprechen.

mastodon.domain

Domain des Servers der deinen Bot hostet. Du brauchst einen normalen User-Account. Acht darauf, ob dein Server Bot-Accounts erlaubt. bot.pnpde.social ist ein Server, der ausschließlich Bots hostet.

mastodon.token

Ein Bearer-Token das der Bot zur Interaktion mit der API deines Servers nutzt. Du kannst ein solches Token z.B. mit Build-A-Bearer erzeugen.

log-file

Dateiname in den die Bots Lognachrichten schreiben.

cache-dir

Verzeichnis das die Bots zum Zwischenspeichern benutzen.

cache-max-age

Zeit, nach der manche Daten im cache-dir erneuert werden sollen.

Beispiel Bots

Alle Beispiele verwenden die oben erstellte config.php

Hello World / bot-hello-world.php

Dieser einfachste Bot macht nichts anderes als "Hello World :)" zu posten. Du kannst den Inhalt von $text ändern um einen anderen Text zu posten. Das Grundgerüst der Instantiierung der Mastodon-Klasse und dem Abschließenden Aufruf von post_status($text) ist das gleiche, wie bei allen folgenden Bots.

Data from API / bot-data-from-api.php

Ein Bot der zeigt, wie man eine JSON-API abfragt, die von dort erhaltenen Daten aufbereitet und postet. Dazu wird zusätzlich inc/functions.php eingebunden, um die Funktionen get($url) und get_json($url) zu nutzen.

Der Bot lädt zuerst eine Liste von URLs von https://shadowdark.dnddeutsch.de/api/monster. Daraus entfernt er bereits gepostete Einträge (dazu gleich) sowie Einträge, deren Schlüssel mit srd5e- beginnt. Danach wird ein zufälliger Schlüssel gewählt, der zugehörige URL um /markdown ergänzt und dieser geladen. Die Antwort wird schließlich gepostet und der Schlüssel wird zusammen mit anderen bereits vorher gemerkten Schlüsseln in einer Datei gespeichert.

💡 Der Bot lädt den Markdown formatierten Werteblock eines Shadowdark-Monsters von der ShadowD3rk-API und postet ihn. Da GoToSocial Markdown unterstützt funktioniert das ohne weiteres.

Eine kaum modifizierte Version dieses Bots ist live als @shadowdark_creatures@bot.pnpde.social

Data from RSS / bot-data-from-rss.php

Ein Bot der einen RSS-Feed abruft und den neusten Beitrag daraus postet. Der Bot benutzt SimplePie, das hier gebundelt ist.

Der Bot lädt den RSS-Feed https://www.dnddeutsch.de/feed/ und durchläuft alle Items des Feeds. Er überspringt zuvor gepostete Items, die er anhand ihrer ID identifiziert. Er setzt den Nachrichtentext aus Title, Link und Description zusammen und kürzt das Ergebnis auf 5000 Zeichen. Dazu sei angemerkt, dass 1.) Mastodon-Server meistens auf 500 Zeichen begrenzt sind. Unsere Bot-Instanz lässt aber das zehnfache zu. Und 2.) ein einfaches Abschneiden auf 500 Zeichen etwas zu einfach wäre, denn Links und Mentions werden gesondert gezählt. Dazu empfehle ich einen Blick in die Mastodon Dokumentation. Nach dem ersten nicht leeren Text, wird die Schleife abgebrochen und abschließend, wenn ID und Text vorliegen, wird der Text gepostet und die ID gemerkt.

💡 Der Bot postet den ersten neuen Eintrag des D3 Feeds.

itch.io Profile / bot-itch-profile.php

Ein Bot der alle RSS-Feeds eines itch.io-Profiles abruft und den neusten Beitrag daraus postet. Der Bot benutzt SimplePie, das hier gebundelt ist.

Der Bot tut im Wesentlichen das Gleiche wie der Data from RSS-Bot, lädt aber neun RSS-Feeds und führt die enthaltenen, ungeposteten Items in einem Array zusammen. Das Array wird nach Datum absteigend sortiert und abschließend wird das neuste Item gepostet.

💡 Der Bot postet den ersten neuen Eintrag aller Feeds eines itch.io-Profils.

Bots ausführen

Die Bots verfügen über keinen eigenen Scheduler, sondern werden direkt gestartet. Sie sind darauf ausgelegt, jeweils einen Status pro Aufruf zu posten. Du kannst sie folgendermaßen aufrufen:

php bot-hello-world.php

Und entsprechend ein ähnlicher Aufruf für die anderen Bot-Dateien. Wenn dein Bot zum Beispiel täglich zur gleichen Uhrzeit posten soll, bietet es sich an einen cronjob einzurichten, zB:

# today in the realms
0 7 * * * /usr/bin/php /opt/today-in-the-realms/bot-today.php
0 10 * * * /usr/bin/php /opt/today-in-the-realms/bot-weather.php --terrain=random --latitude=random

Bots in Produktion

Die Bot-Beispiele konzentrieren sich auf das Zeigen der grundlegenden Mechanismen für einen Bot. Sie sollten nicht in den Produktivbetrieb gehen, sondern sind als Anschauungsmaterial zu behandeln.

2025 CC-BY-SA Thomas Nesges, https://nesg.es