Yii commands in LimeSurvey-Plugins

Der direct-Event ist der offizielle CLI-Einstiegspunkt für LimeSurvey-Plugins – schlank, gezielt, gut für einfache Cronjobs. Aber er hat eine feste Grenze: drei Parameter, kein Routing, keine Argument-Validierung. Wer komplexere Kommandos braucht, stößt schnell an diese Grenze.

Yii 1.1 bringt ein eigenes Command-System mit, das deutlich mächtiger ist. Und es lässt sich so in ein Plugin integrieren, dass die Plugin-Kapselung vollständig erhalten bleibt.

Was Yii Commands können

Ein Yii Command ist eine Klasse, die von CConsoleCommand erbt. In der einfachsten Form überschreibt sie run():

class ExportCommand extends CConsoleCommand
{
    public function run($args): int
    {
        // $args enthält alle Kommandozeilen-Argumente als Array
        echo 'Export läuft' . PHP_EOL;
        return 0;
    }
}

Aufruf:

php application/commands/console.php export

Das ist der Einstieg. Interessanter wird es mit Command Actions.

Command Actions – ein Command, mehrere Sub-Commands

Statt alles in run() zu stopfen, kann ein Command mehrere Actions definieren. Eine Action ist eine Methode nach dem Muster actionXyz(), deren Parameter direkt aus den Kommandozeilenoptionen befüllt werden:

class SurveyCommand extends CConsoleCommand
{
    public function actionExport(int $surveyId, string $format = 'csv'): int
    {
        echo "Exportiere Umfrage $surveyId als $format" . PHP_EOL;
        return 0;
    }

    public function actionCleanup(int $surveyId): int
    {
        echo "Bereinige Umfrage $surveyId" . PHP_EOL;
        return 0;
    }
}

Aufruf:

php application/commands/console.php survey export --surveyId=112233 --format=csv
php application/commands/console.php survey cleanup --surveyId=112233

Parameter werden als benannte Optionen übergeben und direkt auf die Methodenparameter gemappt. Optionale Parameter haben Standardwerte. Wird eine Action weggelassen, greift actionIndex() als Standard. --help funktioniert out of the box.

Das ist ein fundamentaler Unterschied zu direct: Die Schnittstelle ist explizit deklariert, nicht implizit über einen String-Parameter transportiert.

Das Kapselungsproblem

Yii Commands liegen normalerweise in application/commands/. Das ist das Standardverzeichnis, das console.php beim Start registriert. Für Plugin-Entwickler ist das ein Problem: Commands außerhalb des Plugin-Verzeichnisses zu deployen bedeutet, Dateien außerhalb von upload/plugins/MeinPlugin/ zu verteilen. Das bricht das Kapselungsmodell des Plugin-Systems – Deinstallation, Updates und Mehrfachinstallationen werden komplizierter.

Die Lösung steckt bereits in console.php:

$env = (string) @getenv('YII_CONSOLE_COMMANDS');
if (!empty($env)) {
    $app->commandRunner->addCommands($env);
}

console.php liest die Umgebungsvariable YII_CONSOLE_COMMANDS und registriert den darin enthaltenen Pfad als zusätzliches Command-Verzeichnis. Das ist ein offizieller Yii-Mechanismus – dokumentiert seit Version 1.1.1 als Weg, globale Commands außerhalb des Standard-Verzeichnisses bereitzustellen.

Plugin als Container für Commands

Ein Plugin kann sein eigenes commands/-Verzeichnis mitliefern und dieses über YII_CONSOLE_COMMANDS registrieren. Die Plugin-Struktur:

upload/plugins/MeinPlugin/
    config.xml
    MeinPlugin.php
    commands/
        SurveyCommand.php

Der Aufruf setzt die Umgebungsvariable, bevor console.php gestartet wird:

YII_CONSOLE_COMMANDS=/var/www/limesurvey/upload/plugins/MeinPlugin/commands \
php application/commands/console.php survey export --surveyId=112233

Oder als Crontab-Eintrag:

0 2 * * * YII_CONSOLE_COMMANDS=/var/www/limesurvey/upload/plugins/MeinPlugin/commands php /var/www/limesurvey/application/commands/console.php survey export --surveyId=112233

Das Plugin verlässt sein Verzeichnis nicht. Keine Dateien in application/commands/, kein Eingriff in den Core. Der Command läuft trotzdem im vollen LimeSurvey-Kontext – Datenbankzugriff via Yii::app()->db, Zugriff auf ActiveRecord-Modelle, Plugin-Einstellungen, alles verfügbar.

Abgrenzung zu `direct`

Beide Ansätze lösen dasselbe grundlegende Problem – CLI-Zugriff auf LimeSurvey-Funktionalität – aber auf unterschiedlichen Ebenen.

direct ist der richtige Einstiegspunkt für einfache, fokussierte Kommandos: ein Plugin, eine Aufgabe, wenige Parameter. Die Schnittstelle ist minimal, das Setup ist gering. Für einen nächtlichen Datenexport mit einer Survey-ID als Parameter reicht das vollständig aus.

Yii Commands sind die richtige Wahl, sobald ein Kommando wächst: mehrere Sub-Commands, explizite Parameter mit Typen und Standardwerten, Hilfe-Ausgabe, strukturierte Fehlerbehandlung über Exit Codes. Die Deklaration der Schnittstelle geschieht im Code, nicht in der aufrufenden Shell.

Der entscheidende Unterschied ist nicht die Komplexität des einzelnen Aufrufs, sondern die Ausdrucksstärke der Schnittstelle. Bei direct trägt --option alles – einen Survey-ID-String, ein JSON-Konstrukt, was auch immer der Entwickler hineinlegt. Bei einem Yii Command steht actionExport(int $surveyId, string $format = 'csv') – und PHP weiß, was erwartet wird.

Fazit

Yii Commands in LimeSurvey-Plugins sind kein offiziell dokumentierter Erweiterungspunkt – sie sind eine Konsequenz aus dem YII_CONSOLE_COMMANDS-Mechanismus, den console.php bereits mitbringt. Das Plugin bleibt vollständig gekapselt, der Command läuft im vollen LimeSurvey-Kontext, und die Schnittstelle ist so mächtig wie Yii 1.1 sie macht.