Wenn ein Plugin nicht auf eine Benutzeraktion im Browser reagieren soll, sondern auf der Kommandozeile aufgerufen werden – für einen Cronjob, einen Datenexport, eine nächtliche Bereinigung –, dann ist direct der richtige Einstiegspunkt.
Das Minimalbeispiel
Ein LimeSurvey-Plugin besteht aus mindestens zwei Dateien:
upload/plugins/HelloWorld/
config.xml
HelloWorld.php
Der Verzeichnisname, der Klassenname und der <name>-Eintrag in der config.xml müssen identisch sein.
<?xml version="1.0" encoding="UTF-8"?>
<config>
<metadata>
<name>HelloWorld</name>
<type>plugin</type>
<version>1.0.0</version>
<author>My Name</author>
<description><![CDATA[Hello World via CLI]]></description>
</metadata>
<compatibility>
<version>6.0</version>
<version>5.0</version>
</compatibility>
</config>
class HelloWorld extends PluginBase
{
protected $storage = 'LimeSurvey\PluginManager\DbStorage';
static protected $description = 'HelloWorld';
static protected $name = 'HelloWorld';
public function init(): void
{
$this->subscribe('direct');
}
public function direct(): void
{
$event = $this->getEvent();
if ($event->get('target') !== get_class($this)) {
return;
}
echo 'HELLO WORLD' . PHP_EOL;
exit;
}
}
Nach der Aktivierung im Plugin-Manager wird das Plugin so aufgerufen:
php application/commands/console.php plugin --target=HelloWorld
Wie direct funktioniert
Das LimeSurvey-Plugin-System ist event-basiert. Plugins abonnieren Events in init() und reagieren darauf, wenn der Event ausgelöst wird. direct ist der Event für CLI-Aufrufe – er wird gefeuert, wenn der Konsolenbefehl plugin ausgeführt wird.
Das hat eine wichtige Konsequenz: Alle aktiven Plugins, die direct abonniert haben, empfangen denselben Event. Nicht nur das aufgerufene Plugin – alle. Das target-Matching in der direct()-Methode ist deshalb keine Schutzmaßnahme, sondern die einzige Adressierung. Wer die Prüfung weglässt, lässt sein Plugin bei jedem direct-Aufruf reagieren – unabhängig davon, welches Plugin gemeint war.
Abgrenzung zum cron-Event
LimeSurvey kennt einen zweiten CLI-Event: cron. Der Unterschied ist fundamental.
cron ist ein broadcast: php console.php plugin cron --interval=X ruft alle aktiven Plugins auf, die diesen Event abonniert haben. Es gibt kein Targeting, kein einzelnes Plugin wird adressiert. Der --interval-Parameter gibt an, in welchem Rhythmus der Cron ausgeführt wird – Plugins können darüber steuern, ob sie bei diesem Aufruf tatsächlich aktiv werden wollen. Es ist ein systemweiter Takt.
direct ist ein gezielter Aufruf. Ein Plugin, ein Kommando, eine Aufgabe. Der Aufrufer entscheidet explizit, welches Plugin reagieren soll.
Für Cronjobs ist direct deshalb oft die bessere Wahl: Man hat Kontrolle darüber, welches Plugin wann läuft, mit welchen Parametern, und in welcher Reihenfolge – anstatt einen systemweiten Takt zu setzen, der alle registrierten Plugins gleichzeitig aufweckt.
Die Parameter
Der direct-Event kennt drei Parameter:
--target ist der Name des Plugins, das reagieren soll. Pflichtparameter in der Praxis – ohne ihn reagieren alle Plugins, die direct abonniert haben und keine Target-Prüfung implementieren.
--function ist ein optionaler Zusatzparameter als String. Das Manual beschreibt ihn als „extra param for plugin if needed".
--option ist ein weiterer optionaler Parameter. Ebenfalls ein String, ebenfalls undefiniert in seiner Bedeutung – das Plugin selbst entscheidet, wie es ihn interpretiert.
Mehr gibt es nicht. Drei Parameter, alle als Strings, alle ohne definierte Semantik jenseits von target.
Wenn drei Parameter nicht reichen
Drei Parameter sind für einfache Kommandos ausreichend. Sobald ein Plugin flexibler parametrisiert werden soll, stößt man an die Grenzen der Schnittstelle.
Hat der Aufruf Bezug auf eine konkrete Umfrage, ist --option der natürliche Träger der Survey-ID:
php application/commands/console.php plugin --target=MeinPlugin --option=112233
Das Plugin liest die Survey-ID aus --option und greift auf die umfragespezifischen Plugin-Einstellungen zu – Parametrisierung, die im Plugin-Manager pro Umfrage konfiguriert wurde. Für diesen Fall ist das Modell sauber: der Aufruf benennt die Umfrage, die Konfiguration liegt in der Datenbank.
Braucht ein Plugin mehrere Parameter ohne Umfragebezug, kann --option ein JSON-Konstrukt tragen:
php application/commands/console.php plugin --target=MeinPlugin --option='{"modus":"export","format":"csv"}'
Das Plugin parst --option als JSON und extrahiert die benötigten Werte. Es ist ein Workaround – aber ein pragmatischer. Die Alternative wäre, Parameter in der Plugin-Konfiguration zu hinterlegen und den Aufruf selbst schlank zu halten.
Einsatz als Cronjob
Ein typischer Crontab-Eintrag für einen nächtlichen Export:
0 2 * * * php /var/www/limesurvey/application/commands/console.php plugin --target=MeinExportPlugin --option=112233
Das Plugin wird täglich um 2 Uhr aufgerufen, arbeitet die Umfrage mit der ID 112233 ab und beendet sich. Kein Browser, keine Session, kein HTTP-Kontext – nur PHP auf der Kommandozeile mit Zugriff auf die LimeSurvey-Infrastruktur: Datenbankmodelle, Plugin-Einstellungen, Konfiguration.
Genau das macht direct für Cronjobs attraktiv: Das Plugin läuft im vollen LimeSurvey-Kontext, ohne dass ein HTTP-Request nötig ist.
Fazit
direct ist ein schlanker, gezielter Einstiegspunkt für CLI-Kommandos innerhalb des LimeSurvey-Plugin-Systems. Er gibt Plugins Zugriff auf die gesamte LimeSurvey-Infrastruktur, ohne HTTP-Overhead, und lässt sich sauber in Crontabs einbinden. Die Parameterschnittstelle ist bewusst minimal – wer mehr Flexibilität braucht, löst das über Plugin-Einstellungen oder JSON in --option. Wer einen systemweiten Takt braucht, der alle relevanten Plugins gleichzeitig aufruft, greift zum cron-Event. Für alles andere ist direct die richtige Wahl.