Plugin¶

Mit Plugins kann die Funktionsweise der Anwendung erweitert werden. Plugins müssen als Phar-Archive

Installation¶

In der Datei system.ini muss die IncludeApplicationPlugins Einheit aktiviert werden. Dies kann über folgenden Codeblock erfolgen.

; Plugins einbinden
IncludeApplicationPlugins=*

[IncludeApplicationPlugins]
; Konfiguration für das Einbinden von Plugins

Verwalten von Plugins¶

Auf der Konsole stehen Befehle zum Hinzufügen, Aktivieren, Deaktivieren und Löschen eines Plugins zur Verfügung.

Hinweis

Der Parameter --version ist nur notwendig, wenn mehrere Versionen eines Plugins installiert sind.

Hinzufügen¶

Plugins können entweder im Dateisystem liegen oder über eine URL von einem externen Webserver geladen werden. Dazu kommt der Befehl plugin:fetch zum Einsatz. Das Plugin wird im Plugin-Verzeichnis available/<version>/<plugin-phar> available/<version>/<plugin-phar-pubkey> abgelegt. Nach diesem Befehl ist das Plugin noch nicht aktiviert und hat weiter keine Funktion.

# Plugin liegt in einem Verzeichnis im Dateisystem
alvine-platform plugin:fetch \
            --source /tmp/hello-world.phar

# Plugin über URL von entfernten Webserver holen
alvine-platform plugin:fetch \
            --source https://example.com/hello-world.phar

Hinweis

Unter der angegebenen Quelle muss auch der öffentliche Schlüssel liegen. Wird das Plugin https://example.com/hello-world.phar geholt, so wird auch die Datei https://example.com/hello-world.phar.pubkey geladen.

Aktivieren¶

Ein vorhandenes Plugin kann über plugin:enable aktiviert werden. Nach dem Aufruf dieses Befehls wird beim nächsten Aufruf der Anwendung das Plugin eingebunden.

# Im Verzeichnis
alvine-platform plugin:enable \
            --class \\My\\Plugin\\Component

Da der Backslash in vielen Konsolen ein Sonderzeichen ist, muss statt --class \My\Plugin\Component der Backslash maskiert werden: --class \\My\\Plugin\\Component

Hinweis

Liegt das Plugin in mehreren Versionen vor, so muss die Version mitgegeben werden:

# Im Verzeichnis
alvine-platform plugin:enable \
            --class \\My\\Plugin\\Component
            --version 1.1.0

Deaktivieren¶

Ein vorhandenes Plugin kann über plugin:disable deaktiviert werden.

# Im Verzeichnis
alvine-platform plugin:disable \
            --class \\My\\Plugin\\Component

Ab jetzt wird das Plugin nicht mehr verwendet. Das Pluginpaket ist aber noch verfügbar und kann über plugin:enable aktiviert werden.

Löschen¶

Ein vorhandenes, nicht aktives Plugin, kann über plugin:remove von der Festplatte gelöscht werden.

# Im Verzeichnis
alvine-platform plugin:remove \
            --class \\My\\Plugin\\Component

Liegt das Plugin in mehreren Versionen vor, so muss die Version mitgegeben werden:

# Im Verzeichnis
alvine-platform plugin:remove \
            --class \\My\\Plugin\\Component
            --version 1.1.0

Um das Plugin wieder zu aktivieren, muss es mit plugin:fetch neu geholt werden.

Entwicklung¶

Plugins müssen im Format Phar ausgeliefert werden. Die Grundstruktur innerhalb des Phars ist folgendermaßen:

├── default
│   ├── component.properties
│   └── route
│       └── myplugin-route.xml
├── resource
│   └── locale
│       ├── en.properties
│       └── de.properties
├── source
│   ├── Component.class.php
│   └── Presenter.class.php
└── web

Im Stub des Plugins muss der Namespace registriert werden.

<?php
namespace Alvine\Application\Platform\Plugin\HelloWorld;
\Alvine\Core\ComponentLoader::getInstance()->registerNamespace(__NAMESPACE__, 'phar://hello-world-snapshot.phar/source/');
__HALT_COMPILER(); ?>

Alle Plugins müssen im Source-Verzeichnis eine von \Alvine\Application\Platform\Plugin\Component abgeleitete Klasse Component besitzen.

Übersicht über die logische Pluginstruktur:

Aktivieren & Deaktivieren¶

Müssen Plugins weitere Konfigurationen durchführen, so können die Methoden enable() und disable() überschrieben werden.

Im Standardverhalten der Methode enable() werden alle Webdateien aus dem Verzeichnis web in das Anwendungswebverzeichnis vendor/plugins/<name des plugins> kopiert. Alle Routen werden in das Routingverzeichnis kopiert.

Die Standardmethode disable() entfernt diese Dateien wieder.

Abhängigkeiten¶

Abhängigkeiten, bestimmte PHP-Version, PHP-Module oder andere Komponenten müssen über die Methode Component::initEnvironmentRules() definiert werden.

protected function initEnvironmentRules(): \Alvine\Core\Component {
    parent::initEnvironmentRules();

    $this->ruleset->add(new \Alvine\Util\Dependency\Rule\PhpIni('zend.multibyte', true))
        ->add(new \Alvine\Util\Dependency\Rule\Component('myplugin', '1.0.0'))
        ->add(new \Alvine\Util\Dependency\Rule\PhpModule('mbstring'));
}

Konfigurationen¶

Die Standardwerte der Konfigurationseinstellungen stehen in der Datei default/component.properties. Die Konfiguration innerhalb des Plugins muss über Component::getConfiguration() geladen werden.

Regeln¶

Plugins dürfen

Plugincode ausführen
Plugins dürfen Komponenten aktivieren (über Assembly::includeLibrary())
Dürfen auf Plattform-Klassen/Objekte zugreifen.
Dürfen Plattformcode verwenden

Dürfen nicht

Plugins dürfen andere Plugins nicht einbinden
Plugins dürfen keine Komponente (Phar) direkt einbinden, sondern müssen über Assembly::includeLibrary() gehen.

Anpassungen¶

Anpassungen an Plugindateien können über das Customisation-Verzeichnis der Anwendung durchgeführt werden. Anpassungen müssen im Verzeichnis plugins/<name des plugins>/ liegen.

Workflow¶

Verwendet ein Plugin einen Workflow, so kann die Methode Component::getWorkflow('my-workflow') verwendet werden. Die Dateierweiterung .xml kann weggelassen werden. Es kann aber auch der gesamte Dateipfad angegeben werden.

// Nur der Name 
$workflow = \Alvine\Application\Platform\Plugin\Turnover\Component::getInstance()->getWorkflow('my-workflow');

// Name mit Erweiterung 
$workflow = \Alvine\Application\Platform\Plugin\Turnover\Component::getInstance()->getWorkflow('my-workflow.xml');

// Name mit Pafadangabe 
$workflow = \Alvine\Application\Platform\Plugin\Turnover\Component::getInstance()->getWorkflow('/etc/workflow/my-workflow.xml');

Die Workflowdatei wird an folgenden Orten in dieser Reihenfolge gesucht:

An dem genau übergebenen Dateipfade.
Im Unterverzeichnis workflow/plugins/<name des plugins>/ des Konfigurationsverzeichnisses der Anwendung (siehe system.ini).
Im Unterverzeichnis workflow/ des Konfigurationsverzeichnisses der Anwendung (siehe system.ini).
Im Unterverzeichnis workflow im Standardkonfigurationsverzeichnis der Anwendung default/