Loheide-eu-mitarbeiterplatt.../docs/PLUGINS.md
Friederich Loheide 4fcc41ed30
All checks were successful
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 2m41s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 2m48s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 3m15s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 3m17s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 3m48s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 3m41s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 3m33s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m26s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 3m59s
Phase 6 (Teil 2): OpenID Connect, LDAP/AD und SAML 2
- Gemeinsamer Treiber-Unterbau (App\Identity\IdentityDriver, IdentityDrivers,
  IdentityLogin, AttributeProfile); Entra ID nutzt ihn ebenfalls
- Plugins oidc, ldap und saml mit Profil- und Gruppen-Zuordnung
- Admin: Verfahren wählen, Formular je Verfahren, zuletzt empfangene Angaben
- onelogin/php-saml als neue Abhängigkeit

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 12:38:32 +00:00

160 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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, Dokumentordner – Vorlage: `plugins-core/documents`):
`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`.
## Redaktion, Navigation und Benachrichtigungen
- Arbeitslisten im Bereich „Redaktion“: `app(App\Editorial\Editorial::class)->add($key, $label, 'mein-plugin::Liste', $sort, $sichtbar, $props)`.
- 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.
## 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.