Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 7m29s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 7m31s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 9m3s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 9m36s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 13m33s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 13m56s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 12m35s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 11m58s
CI / Bekannte Sicherheitslücken in Paketen (pull_request) Successful in 50s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m13s
- 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>
304 lines
16 KiB
Markdown
304 lines
16 KiB
Markdown
# 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, 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 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)`.
|
||
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 mit `method_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 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 `breadcrumbs`, Symbol `icon`, Slot „actions“). Die Gestaltung wählt das Portal global (Erscheinungsbild → Seitenköpfe); das Symbol stammt ohne `icon` vom passenden Menüpunkt. Rückwege als `breadcrumbs` angeben, 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 mit `visible: 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 unter `resources/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 Ansicht `easy` aus
|
||
`EasyLanguage::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\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:**
|
||
|
||
```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(…)` |
|
||
| 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`.
|
||
|
||
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
|
||
<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`).
|