# 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
```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
```php
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:
```php
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 `` 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))`.
- 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: `` 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 Ansicht `easy` aus
`EasyLanguage::props('typ', $id, $user, $darfBearbeiten)` an ``
übergeben. „text“ ist der Ausgangstext für den KI-Vorschlag – nur, was alle Lesenden sehen.
## 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///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:**
```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
```bash
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///…` 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:
```vue
…
```
### 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`).