fa/breadcrumb-the-shire
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: introduce module system and extract address book as first module (MODULAR-MONOLITH-V1-001)

Browse Source 
Add a module kernel (ModuleManifest, ModuleRegistry) that allows modules to
contribute routes, UI slots, search providers, layout context, session
lifecycle, and permissions. Modules are activated via config/modules.php or
APP_ENABLED_MODULES env variable. Conflicts (duplicate routes, permissions,
slot keys) cause a fail-fast with a clear error message.

Extract the address book from hardcoded Core integration points into the
first module (modules/addressbook/). The module provides:
- Aside icon-bar tab + People panel via UI slot system
- Global search resource via AddressBookSearchProvider
- Layout context data via AddressBookLayoutProvider
- Session lifecycle via AddressBookSessionProvider

Core cleanup removes address-book hardcodings from SearchSqlResourceProvider,
SearchUiMetaProvider, SearchItemMapperProvider, appBuildLayoutNavContext(),
and the aside templates. Permissions (ADDRESS_BOOK_VIEW) and business logic
(AddressBookService) remain in Core as they gate general user visibility.

Includes 38 new tests (894 total), PHPStan level 5 clean, and architecture
tests verifying zero hardcoded address-book references in search/templates.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Felix Schneider
2026-03-18 15:43:25 +01:00
parent d9805c45d3
commit c364e2b46d
33 changed files with 2639 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
lib/Support/Search/SearchItemMapperProvider.php
View File

@@ -2,18 +2,8 @@
namespace MintyPHP\Support\Search;
use MintyPHP\Service\User\UserAvatarService;
class SearchItemMapperProvider
{
/** @var (callable(): UserAvatarService)|null */
private static $userAvatarServiceResolver = null;
public static function configure(callable $userAvatarServiceResolver): void
{
self::$userAvatarServiceResolver = $userAvatarServiceResolver;
}
public static function mapPreviewItem(string $key, array $data, string $query): ?array
{
if ($key === 'users') {
@@ -23,13 +13,6 @@ class SearchItemMapperProvider
$label = $label === '' ? $email : ($label . ' — ' . $email);
}
$url = lurl('admin/users/edit/' . ($data['uuid'] ?? '')) . '?search=' . urlencode($query);
} elseif ($key === 'address-book') {
$label = trim(($data['first_name'] ?? '') . ' ' . ($data['last_name'] ?? ''));
$email = trim((string) ($data['email'] ?? ''));
if ($email !== '') {
$label = $label === '' ? $email : ($label . ' — ' . $email);
}
$url = lurl('address-book/view/' . ($data['uuid'] ?? '')) . '?search=' . urlencode($query);
} elseif ($key === 'permissions') {
$label = (string) ($data['description'] ?? '');
$url = lurl('admin/permissions/edit/' . ($data['id'] ?? '')) . '?search=' . urlencode($query);
@@ -99,15 +82,6 @@ class SearchItemMapperProvider
$title = trim(($data['first_name'] ?? '') . ' ' . ($data['last_name'] ?? ''));
$description = (string) ($data['email'] ?? '');
$url = lurl('admin/users/edit/' . ($data['uuid'] ?? ''));
} elseif ($key === 'address-book') {
$title = trim(($data['first_name'] ?? '') . ' ' . ($data['last_name'] ?? ''));
$description = (string) ($data['email'] ?? '');
$uuid = (string) ($data['uuid'] ?? '');
$url = lurl('address-book/view/' . $uuid);
$userAvatarService = self::userAvatarService();
if ($uuid !== '' && $userAvatarService->hasAvatar($uuid)) {
$image = lurl('admin/users/avatar-file') . '?uuid=' . urlencode($uuid) . '&size=64';
}
} elseif ($key === 'permissions') {
$title = (string) ($data['key'] ?? '');
$description = (string) ($data['description'] ?? '');
@@ -170,18 +144,5 @@ class SearchItemMapperProvider
];
}
private static function userAvatarService(): UserAvatarService
{
if (!is_callable(self::$userAvatarServiceResolver)) {
throw new \RuntimeException('SearchItemMapperProvider is not configured for dependency: ' . UserAvatarService::class);
}
$service = (self::$userAvatarServiceResolver)();
if (!$service instanceof UserAvatarService) {
throw new \RuntimeException('SearchItemMapperProvider resolver returned invalid dependency: ' . UserAvatarService::class);
}
return $service;
}
}

13
lib/Support/Search/SearchSqlResourceProvider.php
View File

@@ -12,7 +12,6 @@ class SearchSqlResourceProvider
{
return [
'users' => 'and exists (select 1 from user_tenants ut where ut.user_id = users.id and ut.tenant_id in (???))',
'address-book' => 'and exists (select 1 from user_tenants ut where ut.user_id = users.id and ut.tenant_id in (???))',
'tenants' => 'and id in (???)',
'departments' => 'and tenant_id in (???)',
];
@@ -23,18 +22,6 @@ class SearchSqlResourceProvider
$like = SearchQueryNormalizer::normalizeLikeQuery($query);
return [
[
'key' => 'address-book',
'label' => t('Address book'),
'permission' => PermissionService::ADDRESS_BOOK_VIEW,
// escape '\\\\' — four backslashes: PHP reduces to two, SQL reduces to one literal backslash escape char.
'countSql' => "select count(*) from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}}",
'countParams' => [$like, $like, $like],
'previewSql' => "select uuid, first_name, last_name, email from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}} order by last_name, first_name limit ?",
'previewParams' => [$like, $like, $like],
'resultSql' => "select uuid, first_name, last_name, email from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}} order by last_name, first_name",
'resultParams' => [$like, $like, $like],
],
[
'key' => 'users',
'label' => t('Users'),

3
lib/Support/Search/SearchUiMetaProvider.php
View File

@@ -5,7 +5,6 @@ namespace MintyPHP\Support\Search;
class SearchUiMetaProvider
{
private const ICONS = [
'address-book' => 'bi-people',
'users' => 'bi-person-badge',
'tenants' => 'bi-buildings',
'departments' => 'bi-diagram-3',
@@ -20,7 +19,6 @@ class SearchUiMetaProvider
];
private const LIST_URL_KEYS = [
'address-book',
'users',
'tenants',
'departments',
@@ -43,7 +41,6 @@ class SearchUiMetaProvider
$encoded = urlencode($query);
return match ($key) {
'address-book' => lurl('address-book') . '?search=' . $encoded,
'users' => lurl('admin/users') . '?search=' . $encoded,
'tenants' => lurl('admin/tenants') . '?search=' . $encoded,
'departments' => lurl('admin/departments') . '?search=' . $encoded,

129
lib/Support/SearchConfig.php
View File

@@ -2,6 +2,8 @@
namespace MintyPHP\Support;
use MintyPHP\App\Module\Contracts\SearchResourceProvider;
use MintyPHP\App\Module\ModuleRegistry;
use MintyPHP\Support\Search\SearchItemMapperProvider;
use MintyPHP\Support\Search\SearchQueryNormalizer;
use MintyPHP\Support\Search\SearchSpecialResourceProvider;
@@ -10,9 +12,26 @@ use MintyPHP\Support\Search\SearchUiMetaProvider;
class SearchConfig
{
/** @var list<SearchResourceProvider> resolved module providers (cached per request) */
private static ?array $moduleProviders = null;
/** @var array<string, SearchResourceProvider> key→provider lookup */
private static array $moduleProviderByKey = [];
public static function tenantScopeFilters(): array
{
return SearchSqlResourceProvider::tenantScopeFilters();
$filters = SearchSqlResourceProvider::tenantScopeFilters();
// Module providers may contribute tenant scope filters via their resource definitions
foreach (self::resolveModuleProviders() as $provider) {
foreach ($provider->resources() as $key => $resource) {
if (isset($resource['tenant_filter']) && $resource['tenant_filter'] !== '') {
$filters[$key] = $resource['tenant_filter'];
}
}
}
return $filters;
}
public static function resources(string $query, string $locale): array
@@ -20,26 +39,134 @@ class SearchConfig
return SearchSqlResourceProvider::resources($query, $locale);
}
/**
* Return module-contributed search resource definitions.
* These are separate from core SQL resources and processed by SearchDataService.
*
* @return array<string, array{label: string, permission: string, count_sql: string, preview_sql: string, result_sql: string, tenant_filter?: string}>
*/
public static function moduleResources(): array
{
$resources = [];
foreach (self::resolveModuleProviders() as $provider) {
foreach ($provider->resources() as $key => $resource) {
$resources[$key] = $resource;
}
}
return $resources;
}
public static function iconForKey(string $key): string
{
// Check module provider key→icon mapping
$moduleProvider = self::$moduleProviderByKey[$key] ?? null;
if ($moduleProvider !== null) {
$mapped = $moduleProvider->mapResultItem($key, []);
if ($mapped !== null && isset($mapped['icon']) && $mapped['icon'] !== '') {
return $mapped['icon'];
}
}
return SearchUiMetaProvider::iconForKey($key);
}
public static function listUrl(string $key, string $query): string
{
// Ensure module providers are resolved before lookup
self::resolveModuleProviders();
$provider = self::$moduleProviderByKey[$key] ?? null;
if ($provider !== null) {
$url = $provider->listUrl($key, urlencode($query));
if ($url !== '') {
return $url;
}
}
return SearchUiMetaProvider::listUrl($key, $query);
}
public static function mapPreviewItem(string $key, array $data, string $query): ?array
{
self::resolveModuleProviders();
$provider = self::$moduleProviderByKey[$key] ?? null;
if ($provider !== null) {
$mapped = $provider->mapResultItem($key, $data);
if ($mapped !== null) {
return ['label' => $mapped['title'], 'url' => $mapped['url']];
}
return null;
}
return SearchItemMapperProvider::mapPreviewItem($key, $data, $query);
}
public static function mapResultItem(string $key, string $label, array $data): ?array
{
self::resolveModuleProviders();
$provider = self::$moduleProviderByKey[$key] ?? null;
if ($provider !== null) {
$mapped = $provider->mapResultItem($key, $data);
if ($mapped !== null) {
return [
'type' => $label,
'title' => $mapped['title'],
'description' => $mapped['subtitle'] ?? '',
'url' => $mapped['url'],
'image' => '',
'icon' => $mapped['icon'] ?? self::iconForKey($key),
];
}
return null;
}
return SearchItemMapperProvider::mapResultItem($key, $label, $data);
}
/**
* Resolve and cache module search providers for the current request.
*
* @return list<SearchResourceProvider>
*/
private static function resolveModuleProviders(): array
{
if (self::$moduleProviders !== null) {
return self::$moduleProviders;
}
self::$moduleProviders = [];
self::$moduleProviderByKey = [];
try {
/** @var ModuleRegistry $registry */
$registry = app(ModuleRegistry::class);
foreach ($registry->getSearchResources() as $providerClass) {
if (!class_exists($providerClass)) {
continue;
}
$provider = new $providerClass();
if ($provider instanceof SearchResourceProvider) {
self::$moduleProviders[] = $provider;
foreach ($provider->resources() as $key => $resource) {
self::$moduleProviderByKey[$key] = $provider;
}
}
}
} catch (\Throwable) {
// fail-open: module registry may not be available
}
return self::$moduleProviders;
}
/**
* Reset cached module providers (for testing).
*/
public static function resetModuleProviders(): void
{
self::$moduleProviders = null;
self::$moduleProviderByKey = [];
}
public static function hotkeyPreviewResource(string $query): ?array
{
return SearchSpecialResourceProvider::hotkeyPreviewResource($query);

48
lib/Support/helpers/app.php
View File

@@ -59,9 +59,6 @@ function setAppContainer(\MintyPHP\App\AppContainer $container): void
static fn (): \MintyPHP\Service\Access\AuthorizationService => $container->get(\MintyPHP\Service\Access\AuthorizationService::class)
);
\MintyPHP\Support\Search\SearchItemMapperProvider::configure(
static fn (): \MintyPHP\Service\User\UserAvatarService => $container->get(\MintyPHP\Service\User\UserAvatarService::class)
);
}
/**
@@ -610,8 +607,19 @@ function appBuildLayoutNavContext(array $layoutAuth, array $session, array $quer
$csrfKey = \MintyPHP\Session::$csrfSessionKey;
$csrfToken = (string) ($session[$csrfKey] ?? '');
return [
// Pre-resolve module UI slot contributions for templates (templates must not call app() directly)
$moduleUiSlots = [];
try {
/** @var \MintyPHP\App\Module\ModuleRegistry $moduleReg */
$moduleReg = app(\MintyPHP\App\Module\ModuleRegistry::class);
$moduleUiSlots = $moduleReg->getUiSlots();
} catch (\Throwable) {
// fail-open
}
$layoutNav = [
'hasAdminPanel' => layoutHasAdminPanel($layoutAuth),
'moduleSlots' => $moduleUiSlots,
'currentTenant' => $currentTenant,
'availableTenants' => $availableTenants,
'tenantQueryParam' => $tenantQueryParam,
@@ -620,19 +628,33 @@ function appBuildLayoutNavContext(array $layoutAuth, array $session, array $quer
'name' => $tenantName,
'hasAvatar' => $tenantHasAvatar,
],
'addressBook' => [
'url' => lurl('address-book'),
'activeSearch' => trim((string) ($query['search'] ?? '')),
'activeTenants' => appNormalizeStringList($query['tenants'] ?? ''),
'activeDepartments' => appNormalizePositiveIntList($query['departments'] ?? ''),
'activeRoles' => appNormalizePositiveIntList($query['roles'] ?? ''),
'activeCustomFilters' => appNormalizeAddressBookCustomFilterQuery($query),
'peopleGroups' => is_array($session['available_departments_by_tenant'] ?? null) ? $session['available_departments_by_tenant'] : [],
],
'bookmarks' => is_array($session['user_bookmarks'] ?? null)
? $session['user_bookmarks']
: ['groups' => [], 'ungrouped' => []],
'csrfKey' => $csrfKey,
'csrfToken' => $csrfToken,
];
// ── Module layout context providers ──────────────────────────────
// Modules can contribute additional layout data via LayoutContextProvider.
// Each provider returns a key-value array that is merged into $layoutNav.
try {
/** @var \MintyPHP\App\Module\ModuleRegistry $moduleRegistry */
$moduleRegistry = app(\MintyPHP\App\Module\ModuleRegistry::class);
/** @var \MintyPHP\App\AppContainer $container */
$container = $GLOBALS['minty_app_container'];
foreach ($moduleRegistry->getLayoutContextProviders() as $providerClass) {
if (!class_exists($providerClass)) {
continue;
}
$provider = new $providerClass();
if ($provider instanceof \MintyPHP\App\Module\Contracts\LayoutContextProvider) {
$layoutNav = array_merge($layoutNav, $provider->provide($session, $container));
}
}
} catch (\Throwable) {
// fail-open: if module registry is not available, skip module providers
}
return $layoutNav;
}