- PageHeader: Kopfband (Standard, kompakt), Kopfband mit Symbol, mit Symbol, kräftiger Titel – Einstellung page_header im Erscheinungsbild - Symbol vom passenden Menüpunkt (aktiv oder per Adresse), Prop icon - In Spalten (z. B. Downloads) schlichte Form statt Band - Zurück-Links als breadcrumbs (IT-Service), Profil bearbeiten mit PageHeader - Plugin-Assets: Fingerabdruck berücksichtigt Änderungszeiten der Dateien Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
16 KiB
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 mitApp\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, icon: 'sparkles');
// 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 mitpermissionResource(). - Zielgruppen:
App\Support\Permissions\Audiences::constrain($query, 'mein_typ', 'tabelle.id', $user)und im Admin-FormularApp\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. resolveUsingliefert die Daten zur Anzeige (bei jedem Aufruf, je Person).nullblendet 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 mitinject('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 unterresources/js/profile/, speichert über eigene Routen). - Optionale mitgelieferte Plugins:
"enabled_by_default": falseinplugin.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). Jeder Bereich hat eine eigene Seite (/redaktion?bereich=<key>). Ab 0.42.0 zusätzlich->meta($key, icon: 'lucide-name', todo: fn (User $u) => ['count' => 3, 'label' => 'warten auf Freigabe'], create: fn (User $u) => ['label' => 'Neu', 'href' => '/…'])– „todo“ erscheint als Zahl in der Leiste und in der Übersicht. Für ältere Portale mitmethod_exists($editorial, 'meta')absichern. - 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 inresources/icons/icons.json, nach Änderungennpm run icons), im Portal<AppIcon name="…" />aus@/components/AppIcon.vue. - Seitenköpfe im Portal:
@/components/PageHeader.vue(Titel, Beschreibung, Pfadbreadcrumbs, Symbolicon, Slot „actions“). Die Gestaltung wählt das Portal global (Erscheinungsbild → Seitenköpfe); das Symbol stammt ohneiconvom passenden Menüpunkt. Rückwege alsbreadcrumbsangeben, nicht als eigenen Link über dem Kopf – im Kopfband steht der Kopf ganz oben. - Menü-Symbol:
add(…, icon: 'calendar-days')– ein Lucide-Name; ohne Angabe ein neutrales Symbol. Dynamische Punkte können'icon'mitliefern. - Dynamische Menüpunkte:
app(Navigation::class)->provider('mein-plugin', fn (Request $request, ?User $user) => [...]); feste Menüpunkte können mitvisible: fn (User $user) => …je Person ausgeblendet werden. - Benachrichtigungen (Glocke im Portal):
$user->notify(new App\Notifications\PortalNotification($titel, $text, $url)). - Symbol in der Kopfzeile (neben der Glocke):
app(App\Layout\HeaderItems::class)->add('mein-plugin', 'mein-plugin::Symbol', fn (User $user) => ['anzahl' => 3] /* oder null */, sort: 10), Komponente unterresources/js/header/Symbol.vue(ab 0.39.0). - Wochenüberblick per E-Mail:
app(App\Digest\Digest::class)->add('mein-plugin', 'Überschrift', $sort, fn (User $user, CarbonImmutable $seit) => [['title' => …, 'url' => …, 'meta' => …, 'text' => …]])– Schlüssel = Plugin-Kürzel (Rollen-Ausschluss gilt), nur Sichtbares liefern, leere Liste = Abschnitt entfällt. - Barrierefreiheit:
<ReadAloud :source="element" />liest Text mit der Sprachausgabe des Geräts vor. Leichte Sprache als zweite Fassung eigener Inhalte:app(App\Accessibility\EasyLanguage::class)->register('typ', fn (int $id, User $user) => ['can_view' => …, 'can_edit' => …, 'title' => …, 'text' => fn () => '…'])(Kürzel nur aus Buchstaben), in der AnsichteasyausEasyLanguage::props('typ', $id, $user, $darfBearbeiten)an<EasyLanguageBar v-model="leicht" :easy="easy" :read-source="…" />übergeben. „text“ ist der Ausgangstext für den KI-Vorschlag – nur, was alle Lesenden sehen.
Anmeldeverfahren
- Eigene Verfahren: Klasse von
App\Identity\IdentityDriverableiten und mitapp(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()undauthenticate()→App\Identity\ExternalUser. Konto, Profil, Rollen und Foto übernimmt der Kern;App\Identity\AttributeProfilehilft 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=truein der.envverbietet 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 austag_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" } }sha256ist optional, wird aber geprüft, wenn angegeben.requires.coreverhindert 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.jsonund die Einstiegsklasse mit einem Menüpunkt und einer Startseiten-Kachel;- einen Controller mit Route;
- eine Seite
resources/js/pages/Index.vueund eine Kachelresources/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(…) |
| Symbol in der Kopfzeile | resources/js/header/Name.vue |
HeaderItems::add(…) (ab 0.39.0) |
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.
Ab 0.45.0 kopiert das Portal diese Dateien beim ersten Aufruf nach
public/plugin-assets/<slug>/<version>/ (gleiche Adresse) – dann liefert sie der Webserver ohne PHP
aus. Ist public/ nicht beschreibbar, bleibt es bei der Auslieferung über PHP. Beim Deaktivieren,
Löschen oder erneuten Hochladen wird die Kopie entfernt; INHAUS_PLUGIN_ASSETS_PATH setzt ein
anderes Ziel. RichTextEditor aus @inhaus/ui lädt ab 0.45.0 erst nach, wenn er angezeigt wird –
Props, v-model und Template-Refs funktionieren unverändert.
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.
- Layout und Rahmen:
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 Repositoryinhaus-plugin-monatsspruch).