Loheide-eu-mitarbeiterplatt.../docs/PLUGINS.md
Friederich Loheide f11a3e24b3
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 3m54s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 4m0s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 4m54s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 4m50s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 7m48s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 7m38s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 6m56s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 7m5s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m17s
Phase 8 Mobil: REST-API, Web-Push, installierbare App (0.25.0)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 08:20:07 +00:00

14 KiB
Raw Permalink 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.

REST-API

Eigene Endpunkte in routes/api.php erscheinen unter /api/v1 (nur mit gültigem Token, Rollen-Ausschluss des Plugins gilt). Details und alle Endpunkte des Kerns: docs/API.md.

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, Aktualisieren und Löschen.

Updates über update_url

Mit "update_url" in plugin.json prüft Inhaus täglich (und auf Knopfdruck unter „Plugins“), ob es eine neue Fassung gibt. Die Adresse muss mit https:// beginnen und liefert eines dieser Formate:

  • Releases von Forgejo, Gitea oder GitHub – z. B. https://git.example.org/api/v1/repos/<owner>/<repo>/releases/latest: Version aus tag_name (ein führendes „v“ entfällt), Download = erstes ZIP unter den Anhängen, Neuerungen aus dem Release-Text. Das Repository muss ohne Anmeldung lesbar sein.

  • Eigenes JSON:

    { "version": "1.2.0", "download_url": "https://…/mein-plugin-1.2.0.zip",
      "sha256": "…", "changelog": "…", "requires": { "core": ">=0.24" } }
    

    sha256 ist optional, wird aber geprüft, wenn angegeben. requires.core verhindert Updates, die eine neuere Inhaus-Version brauchen.

Das Update ersetzt die Dateien des Plugins; Aktivierung, Einstellungen und Daten bleiben, neue Migrationen laufen sofort.

Eigene Oberflächen mit dem Plugin-SDK

Mitgelieferte Plugins werden mit dem Kern gebaut. Kunden-Plugins bringen ihre Vue-Komponenten vorkompiliert mit (dist/). Vue, Inertia und die Portal-Bausteine liefert das Portal über eine Import Map. Alle Plugins nutzen also dieselbe Vue-Instanz, dieselben Farben und dasselbe Erscheinungsbild. Auf dem Kundenserver wird dafür weder Node noch ein Build gebraucht.

Neues Plugin anlegen

php artisan inhaus:make-plugin mav-kalender --name="MAV-Kalender" --author="MAV"
cd plugins/mav-kalender
npm install
npm run build        # erzeugt dist/ – danach unter Administration → Plugins aktivieren
npm run dev          # baut bei jeder Änderung neu (Seite neu laden)
npm run package      # baut und erzeugt mav-kalender-1.0.0.zip zum Hochladen

Mit --path=… legen Sie das Plugin außerhalb des Portals an, etwa als eigenes Repository. Dann laden Sie das ZIP unter „Plugins“ hoch. Das Gerüst enthält:

  • plugin.json und die Einstiegsklasse mit einem Menüpunkt und einer Startseiten-Kachel;
  • einen Controller mit Route;
  • eine Seite resources/js/pages/Index.vue und eine Kachel resources/js/widgets/Hello.vue;
  • resources/css/style.css;
  • inhaus-sdk/: die Build-Voreinstellung und die Design-Tokens, kopiert aus dem Portal.

Komponenten-Arten

Name in PHP: immer slug::Name. Die Datei ergibt sich aus Art und Name:

Art Datei Angemeldet über
Seite resources/js/pages/Name.vue Inertia::render('slug::Name', [...])
Startseiten-Kachel resources/js/widgets/Name.vue Widgets::add($key, 'slug::Name', …)
Pagebuilder-Block resources/js/blocks/Name.vue BlockType::make(…, 'slug::Name')
Abschnitt „Profil bearbeiten“ resources/js/profile/Name.vue ProfileSections::add(…)
Bereich im öffentlichen Profil resources/js/profile-panels/Name.vue ProfilePanels::add(…)
Redaktions-Liste resources/js/editorial/Name.vue Editorial::add(…)

Welche Dateien es gibt, verzeichnet dist/inhaus.json. Das Portal liest diese Datei und liefert Dateien unter /plugin-assets/<slug>/<version>/… aus – ausschließlich aus dist/ aktiver Kunden-Plugins und nur bestimmte Dateitypen (JS, CSS, Bilder, Schriften). Die Version steht in der Adresse, Browser speichern die Dateien deshalb dauerhaft zwischen. Nach einer Änderung also die Version in plugin.json erhöhen.

Was Plugins importieren dürfen

  • vue – die Vue-Instanz des Portals (ref, computed, onMounted …).
  • @inertiajs/vue3 – router, usePage, useForm, Link, Head …
  • @inhaus/ui – die Bausteine des Portals:
    • Layout und Rahmen: AppLayout, PageHeader, Panel, EmptyState.
    • Formulare: FormField, NativeSelect, TreeSelect (durchsuchbarer Baum), PersonPicker (Person suchen), RichTextEditor, Button, Badge, Input, Textarea, Label, Checkbox, Switch.
    • Darstellung: Skeleton, Separator, PersonAvatar, AppIcon (alle Lucide-Symbole des Portals), FileIcon.
    • Mehrteilige Bausteine: Dialog…, DropdownMenu…, Tabs…, Tooltip…, Accordion….
    • Hilfsfunktionen: http / HttpError (JSON-Aufrufe mit CSRF), formatDate, formatShortDate, formatTime, formatRelative, formatMonthYear, colorFor, toast.

Diese Liste ist die öffentliche Schnittstelle (resources/js/sdk/ui.js): Was dort steht, bleibt innerhalb einer Hauptversion erhalten. Andere Pakete (etwa Lucide) bündelt der Build ins Plugin.

Seiten legen sich selbst ins Portal-Layout:

<script setup>
import { AppLayout, PageHeader, Panel } from '@inhaus/ui';
</script>

<template>
    <AppLayout title="MAV-Kalender">
        <PageHeader title="MAV-Kalender" />
        <Panel title="Nächste Sitzungen">…</Panel>
    </AppLayout>
</template>

Styling

Tailwind steht mit den Design-Tokens des Portals zur Verfügung (bg-card, text-brand-text, rounded-xl …), jedoch mit dem Präfix ih:: ih:grid ih:gap-6 ih:lg:grid-cols-2. Das Präfix verhindert, dass die Klassen eines Plugins die des Portals überschreiben. Farben, Ecken und die Schrift folgen damit automatisch dem Erscheinungsbild. Die Portal-Bausteine selbst bringen ihr Styling mit.

Kacheln ohne eigene Oberfläche

Wer keinen Build möchte, füllt die allgemeinen Kacheln des Kerns mit Inhalt:

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