feat: admin dashboard widgets

src/Dashboard/Contract/DashboardWidgetProviderInterface.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Dashboard\Contract;
+
+use App\Model\DashboardWidget;
+
+/**
+ * Assembles one dashboard card.
+ *
+ * A provider never checks roles itself: it names the one role its widget requires and
+ * DashboardWidgetRegistry does the asking, so the security.yaml role_hierarchy stays the single
+ * place where "an admin is also a group admin" is written down.
+ */
+interface DashboardWidgetProviderInterface
+{
+    /**
+     * The role this widget requires, checked with isGranted() — so a widget requiring
+     * ROLE_GROUPS_MANAGER also appears for the roles above it in the hierarchy.
+     */
+    public function getRequiredRole(): string;
+
+    /**
+     * Higher priority widgets come first on the dashboard.
+     */
+    public function getPriority(): int;
+
+    /**
+     * The assembled widget, or null to leave it out entirely.
+     *
+     * Null and a widget with no entries are different answers on purpose: null means this
+     * account has no business seeing the card at all, while an empty entry list means the card
+     * belongs here but has nothing to show right now, and renders its emptyText instead.
+     */
+    public function build(): ?DashboardWidget;
+}