Monatsspruch 1.0.0

Monatsspruch der ÖAB als Startseiten-Kachel für Inhaus (ab 0.12.0):
automatischer Abruf von oeab.de, eigene Angaben je Monat, Admin-Seite,
Packskript für das installierbare ZIP, Tests.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Friederich Loheide 2026-09-26 16:54:56 +00:00
commit cb27dad0e6
10 changed files with 2262 additions and 0 deletions

1
.gitignore vendored Normal file
View file

@ -0,0 +1 @@
dist/

45
README.md Normal file
View file

@ -0,0 +1,45 @@
# Inhaus-Plugin „Monatsspruch“
Zeigt den **Monatsspruch der Ökumenischen Arbeitsgemeinschaft für Bibellesen (ÖAB)**
als Kachel auf der Startseite des Inhaus-Mitarbeiterportals.
- Lädt die Monatssprüche eines Jahres automatisch von
[oeab.de/monatssprueche](https://www.oeab.de/monatssprueche) (einmal im Monat; ab Dezember
auch das kommende Jahr) und speichert sie – fällt oeab.de aus, bleibt der Spruch stehen.
- Kachel mit Text, Bibelstelle, Übersetzung und Quellenhinweis; Position und Sichtbarkeit wie
jede Kachel unter **Administration → Portal → Startseite**.
- **Administration → Portal → Monatsspruch:** Übersicht des Jahres, „Jetzt laden“ und eigene
Angaben für einzelne Monate (z. B. bei Abruffehlern).
> oeab.de bietet keine Schnittstelle; gelesen wird die öffentliche Jahresseite. Ändert sich deren
> Aufbau, meldet die Admin-Seite den Fehler, und der zuletzt geladene Spruch bleibt sichtbar.
> Bitte klären Sie die Nutzung der Bibeltexte (Übersetzungen) mit der ÖAB bzw. den Verlagen.
## Voraussetzungen
Inhaus **0.12.0** oder neuer (nutzt die allgemeine Kachel `core::Quote` – kein eigener Build nötig).
## Installation
1. `bin/package` erzeugt `dist/monatsspruch-<version>.zip`
(oder das ZIP aus den Releases dieses Repositorys verwenden).
2. Im Portal unter **Administration → Plugins → Plugin hochladen** das ZIP wählen.
3. Plugin aktivieren – die Sprüche werden sofort geladen.
## Entwicklung und Tests
Das Plugin in eine Inhaus-Entwicklungsumgebung nach `plugins/monatsspruch` kopieren oder
verlinken, dort aktivieren und die Tests aus dem Inhaus-Verzeichnis ausführen:
vendor-dev/bin/phpunit plugins/monatsspruch/tests
Aufbau:
| Datei | Zweck |
|---|---|
| `plugin.json` | Manifest (Name, Version, Mindestversion von Inhaus) |
| `src/MonatsspruchPlugin.php` | Kachel und Hintergrundaufgabe registrieren |
| `src/OeabParser.php` | Monatssprüche aus der Jahresseite lesen |
| `src/Verses.php` | Laden, Speichern, eigene Angaben |
| `src/Filament/Pages/MonatsspruchSettings.php` | Admin-Seite |
| `tests/` | Tests inkl. gespeicherter Beispielseite |

26
bin/package Executable file
View file

@ -0,0 +1,26 @@
#!/usr/bin/env php
<?php
// Baut das installierbare ZIP: dist/monatsspruch-<version>.zip
// Hochladen unter Administration → Plugins → „Plugin hochladen“, dann aktivieren.
$root = dirname(__DIR__);
$manifest = json_decode(file_get_contents("$root/plugin.json"), true);
@mkdir("$root/dist");
$target = "$root/dist/{$manifest['slug']}-{$manifest['version']}.zip";
@unlink($target);
$zip = new ZipArchive;
$zip->open($target, ZipArchive::CREATE);
foreach (['plugin.json', 'README.md'] as $file) {
$zip->addFile("$root/$file", "{$manifest['slug']}/$file");
}
$files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator("$root/src", FilesystemIterator::SKIP_DOTS));
foreach ($files as $file) {
$zip->addFile($file->getPathname(), $manifest['slug'].'/src/'.substr($file->getPathname(), strlen("$root/src/")));
}
$zip->close();
echo 'dist/'.basename($target).PHP_EOL;

13
plugin.json Normal file
View file

@ -0,0 +1,13 @@
{
"slug": "monatsspruch",
"name": "Monatsspruch",
"version": "1.0.0",
"description": "Der Monatsspruch der Ökumenischen Arbeitsgemeinschaft für Bibellesen (ÖAB) als Kachel auf der Startseite – wird automatisch von oeab.de geladen, einzelne Monate lassen sich im Admin-Bereich anpassen.",
"author": "Loheide",
"namespace": "Inhaus\\Plugins\\Monatsspruch\\",
"class": "Inhaus\\Plugins\\Monatsspruch\\MonatsspruchPlugin",
"requires": {
"core": ">=0.12.0",
"php": ">=8.3"
}
}

View file

@ -0,0 +1,140 @@
<?php
namespace Inhaus\Plugins\Monatsspruch\Filament\Pages;
use App\Support\Settings;
use BackedEnum;
use Filament\Actions\Action;
use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\Textarea;
use Filament\Forms\Components\TextInput;
use Filament\Notifications\Notification;
use Filament\Pages\Page;
use Filament\Schemas\Components\Section;
use Filament\Schemas\Components\Text;
use Filament\Schemas\Schema;
use Filament\Support\Icons\Heroicon;
use Illuminate\Support\Carbon;
use Illuminate\Support\HtmlString;
use Inhaus\Plugins\Monatsspruch\OeabParser;
use Inhaus\Plugins\Monatsspruch\Verses;
use UnitEnum;
class MonatsspruchSettings extends Page
{
protected string $view = 'filament.pages.settings-form';
protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedBookOpen;
protected static string|UnitEnum|null $navigationGroup = 'Portal';
protected static ?int $navigationSort = 60;
protected static ?string $navigationLabel = 'Monatsspruch';
protected static ?string $title = 'Monatsspruch';
protected static ?string $slug = 'monatsspruch';
/** @var array<string, mixed>|null */
public ?array $data = [];
public static function canAccess(): bool
{
return auth()->user()?->can('appearance.manage') ?? false;
}
public function mount(Settings $settings): void
{
$overrides = [];
foreach ((array) $settings->get(Verses::OVERRIDES, []) as $key => $verse) {
$overrides[] = ['month' => $key, 'text' => $verse['text'] ?? '', 'reference' => $verse['reference'] ?? '', 'translation' => $verse['translation'] ?? ''];
}
$this->form->fill(['overrides' => $overrides]);
}
public function form(Schema $schema): Schema
{
return $schema->statePath('data')->components([
Section::make('Geladene Monatssprüche')
->description('Werden automatisch von oeab.de geladen (einmal im Monat, ab Dezember auch das kommende Jahr). Die Kachel „Monatsspruch“ ordnen Sie unter Portal → Startseite an.')
->schema([Text::make(fn () => $this->overview())]),
Section::make('Eigene Angaben')
->description('Überschreibt den geladenen Spruch eines Monats – z. B. bei einem Abruffehler.')
->schema([
Repeater::make('overrides')->hiddenLabel()->defaultItems(0)->addActionLabel('Monat anpassen')->columns(2)
->schema([
Select::make('month')->label('Monat')->required()->native(false)->options(fn () => $this->monthOptions()),
TextInput::make('reference')->label('Bibelstelle')->required()->maxLength(80)->placeholder('z. B. Galater 5,1'),
Textarea::make('text')->label('Text')->required()->rows(2)->maxLength(600)->columnSpanFull(),
TextInput::make('translation')->label('Übersetzung')->maxLength(80)->placeholder('z. B. Lutherbibel 2017'),
]),
]),
]);
}
public function save(Settings $settings): void
{
$overrides = [];
foreach ((array) ($this->form->getState()['overrides'] ?? []) as $row) {
$overrides[$row['month']] = ['text' => trim($row['text']), 'reference' => trim($row['reference']), 'translation' => filled($row['translation'] ?? null) ? trim($row['translation']) : null];
}
$settings->set(Verses::OVERRIDES, $overrides);
Notification::make()->success()->title('Gespeichert')->send();
}
protected function getHeaderActions(): array
{
return [
Action::make('fetch')->label('Jetzt von oeab.de laden')->icon(Heroicon::OutlinedArrowPath)
->action(function (Verses $verses) {
$count = $verses->fetch(now()->year);
$count
? Notification::make()->success()->title("{$count} Monatssprüche für ".now()->year.' geladen')->send()
: Notification::make()->danger()->title('Abruf fehlgeschlagen')->body((string) (app(Settings::class)->get(Verses::STATUS)['error'] ?? ''))->send();
}),
];
}
/**
* @return array<string, string>
*/
private function monthOptions(): array
{
$options = [];
foreach ([now()->year, now()->year + 1] as $year) {
foreach (OeabParser::MONTHS as $number => $name) {
$options[sprintf('%d-%02d', $year, $number)] = "{$name} {$year}";
}
}
return $options;
}
private function overview(): HtmlString
{
$verses = app(Verses::class);
$status = (array) app(Settings::class)->get(Verses::STATUS, []);
$rows = '';
foreach (OeabParser::MONTHS as $number => $name) {
$verse = $verses->forMonth(now()->year, $number);
$current = $number === now()->month;
$rows .= '<tr style="'.($current ? 'font-weight:600' : '').'"><td style="padding:4px 12px 4px 0;white-space:nowrap;vertical-align:top">'.e($name).'</td>'
.'<td style="padding:4px 0">'.($verse ? e($verse['text']).' <span style="opacity:.7">– '.e($verse['reference']).($verse['custom'] ? ' (eigene Angabe)' : '').'</span>' : '<span style="opacity:.6">nicht geladen</span>').'</td></tr>';
}
$info = empty($status['at'])
? 'Noch nicht abgerufen.'
: 'Letzter Abruf '.e(Carbon::parse($status['at'])->locale('de')->diffForHumans()).(! empty($status['error']) ? ' – <span style="color:rgb(220 38 38)">Fehler: '.e($status['error']).'</span>' : ' – erfolgreich.');
return new HtmlString('<p style="margin-bottom:8px;font-size:13px">'.$info.'</p><table style="width:100%;font-size:13px">'.$rows.'</table>');
}
}

View file

@ -0,0 +1,47 @@
<?php
namespace Inhaus\Plugins\Monatsspruch;
use App\Dashboard\Widgets;
use App\Plugins\Plugin;
use Illuminate\Support\Facades\Schedule;
/**
* Monatsspruch der ÖAB als Startseiten-Kachel. Nutzt die allgemeine Kachel
* „core::Quote“ des Kerns – das Plugin braucht deshalb keinen eigenen Build.
*/
class MonatsspruchPlugin extends Plugin
{
public function register(): void
{
$this->app->singleton(Verses::class);
$this->app->make(Widgets::class)->add('monatsspruch.current', 'core::Quote', 'aside', sort: 5, props: function () {
$verse = $this->app->make(Verses::class)->current();
if (! $verse) {
return null; // Kachel ausblenden, solange nichts geladen ist
}
return [
'title' => 'Monatsspruch '.OeabParser::MONTHS[$verse['month']],
'text' => $verse['text'],
'source' => $verse['reference'],
'note' => implode(' · ', array_filter([$verse['translation'], 'Monatsspruch der ÖAB'])).' ·',
'link' => ['label' => 'oeab.de', 'url' => 'https://www.oeab.de/monatssprueche'],
];
}, label: 'Monatsspruch');
}
public function boot(): void
{
Schedule::call(fn () => $this->app->make(Verses::class)->refreshIfNeeded())
->hourly()->name('monatsspruch-refresh')->withoutOverlapping(10);
}
public function activate(): void
{
// Gleich beim Aktivieren laden, damit die Kachel sofort erscheint.
$this->app->make(Verses::class)->refreshIfNeeded();
}
}

64
src/OeabParser.php Normal file
View file

@ -0,0 +1,64 @@
<?php
namespace Inhaus\Plugins\Monatsspruch;
/**
* Liest die Monatssprüche eines Jahres aus der Seite oeab.de/monatssprueche/<Jahr>.
* Die Seite hat keine Schnittstelle; erkannt wird die Folge „Monat – Text – Bibelstelle“.
*/
final class OeabParser
{
public const MONTHS = [1 => 'Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember'];
/** Kürzel hinter der Bibelstelle → Übersetzung */
public const TRANSLATIONS = [
'L' => 'Lutherbibel 2017',
'E' => 'Einheitsübersetzung 2016',
'EÜ' => 'Einheitsübersetzung 2016',
'Z' => 'Zürcher Bibel',
'GNB' => 'Gute Nachricht Bibel',
'B' => 'BasisBibel',
'NGÜ' => 'Neue Genfer Übersetzung',
'H' => 'Hoffnung für alle',
'E / L' => 'Einheitsübersetzung 2016 / Lutherbibel 2017',
];
/**
* @return array<int, array{text: string, reference: string, translation: ?string}> Monat => Spruch
*/
public static function parse(string $html): array
{
$html = preg_replace('#<(script|style|noscript)\b.*?</\1>#is', '', $html) ?? '';
$text = html_entity_decode(strip_tags(preg_replace('#<(br|/p|/div|/h\d|/li|/td|/span|/strong|/em)\b[^>]*>#i', "\n", $html) ?? ''), ENT_QUOTES | ENT_HTML5, 'UTF-8');
$lines = array_values(array_filter(array_map(fn ($l) => trim(preg_replace('/\s+/u', ' ', $l) ?? ''), explode("\n", $text)), fn ($l) => $l !== ''));
$months = array_flip(self::MONTHS);
$result = [];
foreach ($lines as $i => $line) {
if (! isset($months[$line]) || isset($result[$months[$line]])) {
continue;
}
$verse = $lines[$i + 1] ?? '';
$reference = $lines[$i + 2] ?? '';
// Bibelstelle: Buch, Kapitel und Vers, z. B. „Galater 5,1 (L)“ oder „1. Mose 1,31 (E)“
if (mb_strlen($verse) < 10 || isset($months[$verse]) || ! preg_match('/^\S.*\d+\s*,\s*\d+/u', $reference) || mb_strlen($reference) > 80) {
continue;
}
$translation = null;
if (preg_match('/\s*\(([^)]{1,12})\)\s*$/u', $reference, $m)) {
$translation = self::TRANSLATIONS[trim($m[1])] ?? trim($m[1]);
$reference = trim(mb_substr($reference, 0, -mb_strlen($m[0])));
}
$result[$months[$line]] = ['text' => $verse, 'reference' => $reference, 'translation' => $translation];
}
ksort($result);
return $result;
}
}

102
src/Verses.php Normal file
View file

@ -0,0 +1,102 @@
<?php
namespace Inhaus\Plugins\Monatsspruch;
use App\Support\Settings;
use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\Http;
use Throwable;
/**
* Monatssprüche: automatisch geladen (je Jahr gespeichert) und von Hand anpassbar.
*/
class Verses
{
public const SOURCE_URL = 'https://www.oeab.de/monatssprueche/%d';
public const LOADED = 'monatsspruch.loaded'; // [Jahr => [Monat => Spruch]]
public const OVERRIDES = 'monatsspruch.overrides'; // [„Jahr-Monat“ => Spruch]
public const STATUS = 'monatsspruch.status'; // letzter Abruf
/** Nach dieser Zeit wird ein bereits geladenes Jahr erneut abgerufen (Korrekturen der ÖAB). */
public const REFRESH_DAYS = 30;
public function __construct(private readonly Settings $settings) {}
/**
* @return array{year: int, month: int, text: string, reference: string, translation: ?string, custom: bool}|null
*/
public function forMonth(int $year, int $month): ?array
{
$override = ((array) $this->settings->get(self::OVERRIDES, []))[sprintf('%d-%02d', $year, $month)] ?? null;
if (is_array($override) && filled($override['text'] ?? null)) {
return ['year' => $year, 'month' => $month, 'text' => $override['text'], 'reference' => (string) ($override['reference'] ?? ''), 'translation' => $override['translation'] ?? null, 'custom' => true];
}
$loaded = ((array) $this->settings->get(self::LOADED, []))[$year][$month] ?? null;
return is_array($loaded) ? ['year' => $year, 'month' => $month, ...$loaded, 'custom' => false] : null;
}
public function current(): ?array
{
$now = Carbon::now();
return $this->forMonth($now->year, $now->month);
}
/**
* Lädt ein Jahr von oeab.de. Gibt die Anzahl gefundener Monate zurück.
*/
public function fetch(int $year): int
{
try {
$response = Http::timeout(20)->connectTimeout(8)
->withHeaders(['User-Agent' => 'Inhaus-Mitarbeiterportal (Plugin Monatsspruch)'])
->get(sprintf(self::SOURCE_URL, $year));
if (! $response->successful()) {
throw new \RuntimeException('oeab.de antwortet mit HTTP '.$response->status().'.');
}
$verses = OeabParser::parse($response->body());
if ($verses === []) {
throw new \RuntimeException('Auf der Seite wurden keine Monatssprüche gefunden – der Aufbau von oeab.de hat sich vermutlich geändert.');
}
} catch (Throwable $e) {
$this->settings->set(self::STATUS, ['at' => now()->toIso8601String(), 'year' => $year, 'error' => $e->getMessage()]);
logger()->warning('Monatsspruch: '.$e->getMessage());
return 0;
}
$loaded = (array) $this->settings->get(self::LOADED, []);
$loaded[$year] = $verses;
$this->settings->set(self::LOADED, array_filter($loaded, fn ($y) => $y >= now()->year - 1, ARRAY_FILTER_USE_KEY));
$this->settings->set(self::STATUS, ['at' => now()->toIso8601String(), 'year' => $year, 'error' => null, 'count' => count($verses)]);
return count($verses);
}
/**
* Hintergrundaufgabe: aktuelles Jahr laden, wenn es fehlt oder veraltet ist;
* ab Dezember auch das kommende Jahr.
*/
public function refreshIfNeeded(): void
{
$status = (array) $this->settings->get(self::STATUS, []);
$loaded = (array) $this->settings->get(self::LOADED, []);
$stale = empty($status['at']) || Carbon::parse($status['at'])->lt(now()->subDays(self::REFRESH_DAYS));
$retry = ! empty($status['error']) && Carbon::parse($status['at'])->lt(now()->subHours(6));
foreach (array_unique([now()->year, now()->month === 12 ? now()->year + 1 : now()->year]) as $year) {
if (empty($loaded[$year]) || $stale || $retry) {
$this->fetch($year);
}
}
}
}

100
tests/MonatsspruchTest.php Normal file
View file

@ -0,0 +1,100 @@
<?php
namespace Tests\Plugins\Monatsspruch;
use App\Models\User;
use App\Support\Settings;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\Http;
use Inertia\Testing\AssertableInertia as Assert;
use Inhaus\Plugins\Monatsspruch\OeabParser;
use Inhaus\Plugins\Monatsspruch\Verses;
use Tests\TestCase;
/**
* Läuft innerhalb einer Inhaus-Installation, in der das Plugin unter plugins/monatsspruch liegt:
* vendor-dev/bin/phpunit plugins/monatsspruch/tests
*/
class MonatsspruchTest extends TestCase
{
use RefreshDatabase;
private ?string $previousState = null;
protected function setUp(): void
{
parent::setUp();
// Plugin für diesen Test aktivieren (Kunden-Plugins sind nach der Installation aus).
$file = storage_path('app/plugins.json');
$this->previousState = is_file($file) ? file_get_contents($file) : null;
$state = json_decode($this->previousState ?? '{}', true) ?: [];
$state['monatsspruch'] = ['enabled' => true];
file_put_contents($file, json_encode($state));
$this->refreshApplication();
$this->setUpTraits();
Carbon::setTestNow('2026-10-07 09:00');
}
protected function tearDown(): void
{
$file = storage_path('app/plugins.json');
$this->previousState === null ? @unlink($file) : file_put_contents($file, $this->previousState);
Carbon::setTestNow();
parent::tearDown();
}
private function fixture(): string
{
return (string) file_get_contents(__DIR__.'/fixtures/oeab-2026.html');
}
public function test_parser_reads_all_months_with_reference_and_translation(): void
{
$verses = OeabParser::parse($this->fixture());
$this->assertCount(12, $verses);
$this->assertSame('Galater 5,1', $verses[10]['reference']);
$this->assertSame('Lutherbibel 2017', $verses[10]['translation']);
$this->assertStringStartsWith('Zur Freiheit hat uns Christus befreit!', $verses[10]['text']);
$this->assertSame('Einheitsübersetzung 2016', $verses[1]['translation']);
}
public function test_verses_are_fetched_and_shown_as_dashboard_tile(): void
{
Http::fake(['www.oeab.de/monatssprueche/2026' => Http::response($this->fixture())]);
app(Verses::class)->refreshIfNeeded();
$this->actingAs(User::factory()->create())->get('/')->assertInertia(fn (Assert $page) => $page->where(
'widgets',
fn ($widgets) => ($tile = collect($widgets)->firstWhere('key', 'monatsspruch.current'))
&& $tile['component'] === 'core::Quote'
&& $tile['props']['title'] === 'Monatsspruch Oktober'
&& $tile['props']['source'] === 'Galater 5,1'
));
// Weiterer Aufruf innerhalb von 30 Tagen lädt nicht erneut.
app(Verses::class)->refreshIfNeeded();
Http::assertSentCount(1);
}
public function test_failures_keep_the_last_verse_and_overrides_win(): void
{
Http::fake(['*' => Http::response('<html>Wartung</html>')]);
$this->assertSame(0, app(Verses::class)->fetch(2026));
$this->assertNull(app(Verses::class)->current(), 'Ohne Spruch keine Kachel');
$this->assertStringContainsString('keine Monatssprüche', app(Settings::class)->get(Verses::STATUS)['error']);
app(Settings::class)->set(Verses::OVERRIDES, ['2026-10' => ['text' => 'Eigener Spruch', 'reference' => 'Psalm 1,1', 'translation' => null]]);
$this->assertSame('Eigener Spruch', app(Verses::class)->current()['text']);
$this->assertTrue(app(Verses::class)->current()['custom']);
}
public function test_admin_page(): void
{
$this->actingAs(User::factory()->admin()->create())->get('/admin/monatsspruch')->assertOk()->assertSee('Monatsspruch');
}
}

1724
tests/fixtures/oeab-2026.html vendored Normal file

File diff suppressed because it is too large Load diff