All checks were successful
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 2m55s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 2m44s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 3m25s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 3m39s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 3m47s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 3m51s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 3m16s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 3m25s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m10s
- Admin → Portal → Menü: Bereiche, Seiten (mit Unterseiten), Links und Gruppen mit Unterpunkten, sortierbar, je Rolle einschränkbar; Kopfzeile misst den Platz und legt Überzähliges unter „Mehr“ - Initialen in fester Farbe je Person, Abteilungsfarben im Organigramm - PageHeader für alle Übersichtsseiten - Dokumente: Favoriten (auch als Startseiten-Kachel), „Häufig genutzt“, Vorschaubilder (Bilder, erste PDF-Seite per pdf.js im Browser) - Platzhalter beim Nachladen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
163 lines
7.8 KiB
Markdown
163 lines
7.8 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);
|
||
|
||
// 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)`.
|
||
- 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)`.
|
||
- 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.
|
||
|
||
## 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.
|