Loheide-eu-mitarbeiterplatt.../docs/PLUGINS.md
Friederich Loheide 6bede3e2ee
All checks were successful
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 3m14s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 3m17s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 3m35s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 3m43s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 5m14s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 5m18s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 5m16s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 5m11s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m40s
Update: ersetzten Plugin-Ordner ignorieren; Uploads trotz open_basedir
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 18:45:09 +00:00

8.5 KiB
Raw Blame History

Plugins entwickeln

Inhaus lässt sich wie WordPress über Plugins erweitern. Auch die mitgelieferten Funktionen „Neuigkeiten“ und „Termine“ sind Plugins (plugins-core/news, plugins-core/events) – sie sind die beste Vorlage.

Aufbau

mein-plugin/
  plugin.json               Manifest (Pflicht)
  src/Plugin.php            Einstiegsklasse, erbt von App\Plugins\Plugin
  src/…                     weiterer PHP-Code (PSR-4 unter „namespace“)
  src/Filament/Resources/   Admin-Seiten (werden automatisch gefunden)
  src/Filament/Pages/
  database/migrations/      laufen bei Aktivierung und nach Updates
  routes/web.php            Routen (Middleware „web“ ist gesetzt)
  resources/views/          Blade-Views, Namespace = Kürzel: view('mein-plugin::seite')
  vendor/                   eigene Abhängigkeiten – bitte gescoped (Strauss/PHP-Scoper)

plugin.json

{
    "slug": "mein-plugin",
    "name": "Mein Plugin",
    "version": "1.0.0",
    "description": "Wofür das Plugin da ist.",
    "author": "Firma GmbH",
    "namespace": "Firma\\MeinPlugin\\",
    "class": "Firma\\MeinPlugin\\Plugin",
    "requires": { "core": ">=0.3.0", "php": ">=8.3", "plugins": ["news"] }
}
  • slug: Kleinbuchstaben, Ziffern, Bindestriche; eindeutig. Kürzel mitgelieferter Plugins sind vergeben.
  • namespace: darf nicht mit App\ beginnen.
  • requires.core / requires.php: Versionsbedingungen (>=, <, ^, ~, exakt).
  • requires.plugins: Plugins, die aktiv sein müssen.

Einstiegsklasse

namespace Firma\MeinPlugin;

use App\Dashboard\Widgets;
use App\Plugins\Hooks;
use App\Plugins\Plugin as BasePlugin;
use App\Support\Abilities;
use App\Support\Navigation;

class Plugin extends BasePlugin
{
    public function register(): void
    {
        // Menüpunkt im Portal
        $this->app->make(Navigation::class)->add('mein-plugin', 'Mein Bereich', '/mein-bereich', active: 'mein-plugin.*', sort: 40);

        // Rechte, die im Rollen-Formular erscheinen
        $this->app->make(Abilities::class)->define('mein-plugin.manage', 'Mein Bereich verwalten', 'Mein Plugin');
    }

    public function boot(): void
    {
        Hooks::on('news.post.published', fn ($post) => /* … */ null);
        Hooks::filter('navigation.items', fn (array $items) => $items);
    }

    public function activate(): void {}   // nach „Aktivieren“ (Migrationen sind schon gelaufen)
    public function deactivate(): void {} // vor „Deaktivieren“
    public function uninstall(): void {}  // bei „Mit Daten löschen“ (Tabellen entfernt der Kern)
}

Rechte und Sichtbarkeit

  • Globale Rechte: $abilities->define('schluessel', 'Bezeichnung', 'Gruppe'), prüfen mit $user->can('schluessel').
  • Objekt-Rechte: define(..., resource: 'mein_typ') plus $abilities->resourceType('mein_typ', 'Bezeichnung', fn () => [id => 'Name']); prüfen mit $user->can('schluessel', ['mein_typ', $id]) oder einem Modell mit permissionResource().
  • Zielgruppen: App\Support\Permissions\Audiences::constrain($query, 'mein_typ', 'tabelle.id', $user) und im Admin-Formular App\Filament\Components\AudienceSection::make('mein_typ').
  • Hierarchische Objekttypen (z. B. Seiten, Download-Ordner – Vorlage: plugins-core/downloads): resourceType(..., descendants: fn (array $ids) => [...]). Rechte mit „inkl. Unterobjekten“ gelten dann auch für alle Nachfahren; ändert sich der Baum, App\Support\Permissions\Permissions::flush() aufrufen.
  • Admin-Seiten: Policies registrieren (Gate::policy(Model::class, Policy::class)) bzw. canAccess() an Filament-Seiten.

Pagebuilder-Blöcke

Eigene Blöcke erscheinen im Pagebuilder mit Formular und Absicherung – aus der Feldbeschreibung erzeugt:

use App\Pagebuilder\{Blocks, BlockType, Field};

$this->app->make(Blocks::class)->add(BlockType::make('mein-plugin.liste', 'Meine Liste', 'list-checks', 'dynamic', 'mein-plugin::Liste')
    ->fields([
        Field::text('title', 'Überschrift', 150),
        Field::number('count', 'Anzahl', 1, 20, 5),
        Field::select('layout', 'Darstellung', ['list' => 'Liste', 'cards' => 'Kacheln'], 'list'),
    ])
    ->resolveUsing(fn (array $data, ?User $user, array $context) => ['items' => /* für $user sichtbare Einträge */ []]));
  • Feldtypen: text, textarea, html, select, toggle, number, url, image, people, table, icon, repeater, ids. Unbekannte Felder und Blöcke verwirft der Kern beim Speichern; HTML und Adressen werden bereinigt.
  • resolveUsing liefert die Daten zur Anzeige (bei jedem Aufruf, je Person). null blendet den Block aus; Fehler blenden nur diesen Block aus.
  • Container-Blöcke: ->container(min, max, titled: true, label: 'Tab').
  • Die Vue-Komponente erhält block (data, items, props) – Kinder werden mit inject('pagebuilder:list') gerendert. inject('pagebuilder:editing') ist im Editor wahr.

Startseite und Profil

  • Kacheln: app(App\Dashboard\Widgets::class)->add($key, 'mein-plugin::Kachel', 'aside', sort: 20, props: fn (User $user) => [...], label: 'Name im Admin'). Bereiche: top, hero, feed, main, aside. Admins sortieren und blenden Kacheln unter „Startseite“ aus.
  • Abschnitt in „Profil bearbeiten“: app(App\Profile\ProfileSections::class)->add($key, 'mein-plugin::Abschnitt', $sort, fn (User $user) => [...]) (Komponente unter resources/js/profile/, speichert über eigene Routen).
  • Optionale mitgelieferte Plugins: "enabled_by_default": false in plugin.json.
  • Umbenannte mitgelieferte Plugins: "replaces": ["alter-slug"] – der Updater löscht nie, der alte Ordner bleibt liegen und wird so ignoriert.

Redaktion, Navigation und Benachrichtigungen

  • Arbeitslisten im Bereich „Redaktion“: app(App\Editorial\Editorial::class)->add($key, $label, 'mein-plugin::Liste', $sort, $sichtbar, $props).
  • Eigene Menüpunkt-Arten für den Menü-Editor (Admin → Menü), z. B. „Seite“: app(Navigation::class)->source('typ', 'Bezeichnung', fn () => [id => 'Name'], fn (string $id, array $item, Request $request, ?User $user) => ['label' => …, 'href' => …, 'active' => …, 'children' => [...]] ?: null).
  • Symbole: App\Support\Icons (alle Lucide-Symbole lokal; kuratierte Auswahl in resources/icons/icons.json, nach Änderungen npm run icons), im Portal <AppIcon name="…" /> aus @/components/AppIcon.vue.
  • Seitenköpfe im Portal: @/components/PageHeader.vue (Titel, Beschreibung, Pfad, Slot „actions“).
  • Dynamische Menüpunkte: app(Navigation::class)->provider('mein-plugin', fn (Request $request, ?User $user) => [...]); feste Menüpunkte können mit visible: fn (User $user) => … je Person ausgeblendet werden.
  • Benachrichtigungen (Glocke im Portal): $user->notify(new App\Notifications\PortalNotification($titel, $text, $url)).

Anmeldeverfahren

  • Eigene Verfahren: Klasse von App\Identity\IdentityDriver ableiten und mit app(App\Identity\IdentityDrivers::class)->add('mein-typ', MeinDriver::class) anmelden. Vorlagen: plugins-core/oidc (Weiterleitung), plugins-core/ldap (eigenes Formular), plugins-core/saml (POST-Rückkehr, Metadaten).
  • Der Treiber liefert Formularfelder (connectionSchema()), start() und authenticate() → App\Identity\ExternalUser. Konto, Profil, Rollen und Foto übernimmt der Kern; App\Identity\AttributeProfile hilft beim Auslesen der Attribute.

Installation und Betrieb

  • Als ZIP unter Administration → Plugins hochladen (ein gemeinsamer Ordner im Archiv ist erlaubt), dann aktivieren.
  • Kunden-Plugins liegen in plugins/ und werden von Aktualisierungen nie verändert.
  • Wirft ein Plugin beim Laden einen Fehler – oder bringt es den PHP-Prozess zum Absturz –, wird es automatisch deaktiviert; der Grund steht auf der Plugins-Seite.
  • INHAUS_DISALLOW_FILE_MODS=true in der .env verbietet Hochladen und Löschen.

Kacheln ohne eigene Oberfläche

Kunden-Plugins können (bis zum Plugin-SDK) keine eigenen Vue-Komponenten mitbringen, aber die allgemeinen Kacheln des Kerns mit Inhalt füllen:

  • core::Quote – Spruch/Zitat: title, text, source, note, link ({label, url}). Beispiel: das Plugin „Monatsspruch“ (eigenes Repository inhaus-plugin-monatsspruch).

Derzeit noch nicht für Kunden-Plugins

Vue-Seiten und Startseiten-Kacheln werden beim Build des Kerns mitkompiliert – das geht nur für mitgelieferte Plugins. Für Kunden-Plugins folgt mit dem öffentlichen Plugin-SDK (Phase 7) ein Weg über vorkompilierte ES-Module und eine Import-Map. Bis dahin können Kunden-Plugins Blade-Seiten, Admin-Seiten, Hooks, Rechte und Menüpunkte beitragen.