breadcrumb-the-shire/core/Support/helpers/app.php

<?php

/**
 * HTML-escape output in templates.
 */
function e($string): void
{
    echo htmlspecialchars((string) $string, ENT_QUOTES, 'UTF-8');
}

/**
 * Parse a string setting value as boolean.
 *
 * Accepts common truthy values ('1', 'true', 'yes', 'on') and returns
 * the given default for null, empty strings, or unrecognized values.
 */
function settingToBool(?string $value, bool $default = false): bool
{
    if ($value === null || $value === '') {
        return $default;
    }
    $normalized = strtolower(trim($value));
    if (in_array($normalized, ['1', 'true', 'yes', 'on'], true)) {
        return true;
    }
    if (in_array($normalized, ['0', 'false', 'no', 'off'], true)) {
        return false;
    }
    return $default;
}

/**
 * Resolve the profile target for the current session user.
 */
function accountUrl(): string
{
    $user = $_SESSION['user'] ?? [];
    $uuid = (string) ($user['uuid'] ?? '');
    return $uuid !== '' ? lurl('profile') : lurl('login');
}

/**
 * Build a web asset URL relative to the app base URL.
 */
function asset(string $path): string
{
    return \MintyPHP\Router::getBaseUrl() . ltrim($path, '/');
}

/**
 * Build an absolute filesystem path inside templates/.
 */
function templatePath(string $path): string
{
    return dirname(__DIR__, 3) . '/templates/' . ltrim($path, '/');
}

/**
 * Register the app service container for the current request.
 */
function setAppContainer(\MintyPHP\App\AppContainer $container): void
{
    $GLOBALS['minty_app_container'] = $container;

    \MintyPHP\Http\ApiAuth::configure(
        static fn (): \MintyPHP\Service\Tenant\TenantScopeService => $container->get(\MintyPHP\Service\Tenant\TenantScopeService::class),
        static fn (): \MintyPHP\Service\Auth\ApiTokenService => $container->get(\MintyPHP\Service\Auth\ApiTokenService::class),
        static fn (): \MintyPHP\Repository\Access\UserRoleRepository => $container->get(\MintyPHP\Repository\Access\UserRoleRepository::class),
        static fn (): \MintyPHP\Repository\Access\RolePermissionRepository => $container->get(\MintyPHP\Repository\Access\RolePermissionRepository::class),
        static fn (): \MintyPHP\Service\User\UserTenantContextService => $container->get(\MintyPHP\Service\User\UserTenantContextService::class),
        static fn (): \MintyPHP\Service\Access\AuthorizationService => $container->get(\MintyPHP\Service\Access\AuthorizationService::class)
    );

    \MintyPHP\Http\ApiBootstrap::configure(
        static fn (): \MintyPHP\Service\Audit\ApiAuditServiceInterface => $container->get(\MintyPHP\Service\Audit\ApiAuditServiceInterface::class),
        static fn (): \MintyPHP\Service\Settings\SettingsApiPolicyGateway => $container->get(\MintyPHP\Service\Settings\SettingsApiPolicyGateway::class),
        static fn (): \MintyPHP\Service\Security\RateLimiterService => $container->get(\MintyPHP\Service\Security\RateLimiterService::class),
        static fn (): \MintyPHP\Service\Audit\ApiSystemAuditReporterInterface => $container->get(\MintyPHP\Service\Audit\ApiSystemAuditReporterInterface::class)
    );

    \MintyPHP\Http\ApiResponse::configure(
        static fn (): \MintyPHP\Service\Audit\ApiAuditServiceInterface => $container->get(\MintyPHP\Service\Audit\ApiAuditServiceInterface::class),
        static fn (): \MintyPHP\Service\Access\AuthorizationService => $container->get(\MintyPHP\Service\Access\AuthorizationService::class),
        static fn (): \MintyPHP\Service\Audit\ApiSystemAuditReporterInterface => $container->get(\MintyPHP\Service\Audit\ApiSystemAuditReporterInterface::class)
    );

    \MintyPHP\Support\Guard::configure(
        static fn (): \MintyPHP\Service\Auth\AuthService => $container->get(\MintyPHP\Service\Auth\AuthService::class),
        static fn (): \MintyPHP\Service\Tenant\TenantService => $container->get(\MintyPHP\Service\Tenant\TenantService::class),
        static fn (): \MintyPHP\Service\Access\AuthorizationService => $container->get(\MintyPHP\Service\Access\AuthorizationService::class)
    );

    \MintyPHP\Support\SearchConfig::configure(
        static fn (): \MintyPHP\App\Module\ModuleRegistry => $container->get(\MintyPHP\App\Module\ModuleRegistry::class),
        static fn (string $class): ?object => \MintyPHP\App\Module\ModuleClassResolver::resolve($container, $class)
    );

}

/**
 * Resolve a service from the app container.
 */
function app(string $id): mixed
{
    $container = $GLOBALS['minty_app_container'] ?? null;
    if (!$container instanceof \MintyPHP\App\AppContainer) {
        throw new \RuntimeException('App container is not initialized');
    }

    return $container->get($id);
}

/**
 * Build an asset URL with filemtime cache-busting when available.
 */
function assetVersion(string $path): string
{
    $path = ltrim($path, '/');
    $file = dirname(__DIR__, 3) . '/web/' . $path;
    $url = asset($path);
    $version = @filemtime($file);
    if ($version === false) {
        return $url;
    }
    return $url . '?v=' . $version;
}

/**
 * Base URL including locale segment (e.g. /de/).
 */
function localeBase(): string
{
    $locale = \MintyPHP\I18n::$locale ?? \MintyPHP\I18n::$defaultLocale;
    $prefix = $locale !== '' ? $locale . '/' : '';
    return \MintyPHP\Router::getBaseUrl() . $prefix;
}

/**
 * Locale-aware URL for app routes.
 */
function lurl(string $path = ''): string
{
    return localeBase() . ltrim($path, '/');
}

/**
 * Locale-aware URL for an endpoint, resolved through the module route map.
 *
 * Same as lurl(), but if the given path is a registered module route
 * source path it returns a URL pointing at the route TARGET path instead.
 *
 * Why this exists: MintyPHP's Router::applyRoutes() compares the full
 * request URI (including `?query`) against registered source paths, so a
 * browser navigation to `/admin/foo?x=1` misses the rewrite for a module
 * route `admin/foo → some/other/foo` and falls back to file-based routing
 * — which cannot find `admin/foo`. Using the target path up-front sidesteps
 * the rewrite entirely and works regardless of query string.
 *
 * Use endpointUrl() for URLs that will carry query params (data endpoints,
 * export downloads, AJAX calls). Plain lurl() is still fine for nav links
 * without a query string.
 */
function endpointUrl(string $path = ''): string
{
    $path = ltrim($path, '/');
    try {
        $registry = app(\MintyPHP\App\Module\ModuleRegistry::class);
    } catch (\Throwable) {
        return lurl($path);
    }
    foreach ($registry->getRoutes() as $route) {
        if (($route['path'] ?? '') === $path) {
            $target = (string) ($route['target'] ?? '');
            if ($target !== '') {
                return lurl($target);
            }
        }
    }
    return lurl($path);
}

/**
 * App title from settings with APP_NAME fallback.
 */
function appTitle(): string
{
    $default = defined('APP_NAME') ? APP_NAME : 'CoreCore';
    $title = appSetting('app_title');
    if ($title !== null) {
        return $title;
    }
    return $default;
}

/**
 * Build an absolute URL using APP_URL or request host fallback.
 */
function appUrl(string $path = ''): string
{
    if ($path !== '' && preg_match('#^https?://#i', $path)) {
        return $path;
    }
    // Prefer configured canonical URL to keep links stable.
    $base = getenv('APP_URL') ?: '';
    $base = rtrim((string) $base, '/');
    if ($base === '') {
        $scheme = 'http';
        $https = $_SERVER['HTTPS'] ?? '';
        $forwarded = $_SERVER['HTTP_X_FORWARDED_PROTO'] ?? '';
        if ($https === 'on' || $https === '1' || $forwarded === 'https') {
            $scheme = 'https';
        }
        $host = $_SERVER['HTTP_HOST'] ?? '';
        if ($host !== '') {
            $base = $scheme . '://' . $host;
        }
    }
    if ($base === '') {
        return \MintyPHP\Router::getBaseUrl() . ltrim((string) $path, '/');
    }
    $path = ltrim((string) $path, '/');
    return $base . '/' . $path;
}

/**
 * Human-readable current user name fallback: first+last -> email.
 */
function currentUserDisplayName(): string
{
    $user = $_SESSION['user'] ?? [];
    $name = trim((string) (($user['first_name'] ?? '') . ' ' . ($user['last_name'] ?? '')));
    if ($name !== '') {
        return $name;
    }
    return trim((string) ($user['email'] ?? ''));
}

/**
 * Read one cached app setting from storage/runtime/settings.php.
 */
function appSetting(string $key): ?string
{
    if (!class_exists('MintyPHP\\Service\\Settings\\SettingCacheService')) {
        return null;
    }

    return app(\MintyPHP\Service\Settings\SettingCacheService::class)->get($key);
}

/**
 * Resolve default locale only if it exists in APP_LOCALES.
 */
function appDefaultLocale(): ?string
{
    $locale = appSetting('app_locale');
    if ($locale === null) {
        return null;
    }
    $available = defined('APP_LOCALES') ? APP_LOCALES : [];
    if ($available && !in_array($locale, $available, true)) {
        return null;
    }
    return $locale;
}

/**
 * Feature flag: allow users to choose their own theme.
 *
 * Resolved from the current tenant; defaults to true when no tenant is in
 * session or the tenant has no explicit value. Appearance is tenant-scoped —
 * there is no global setting fallback.
 */
function allowUserTheme(): bool
{
    $tenantValue = $_SESSION['current_tenant']['allow_user_theme'] ?? null;
    if ($tenantValue !== null && (string) $tenantValue !== '') {
        return settingToBool((string) $tenantValue, true);
    }

    return true;
}

/**
 * Feature flag: allow public self-registration.
 */
function allowRegistration(): bool
{
    return settingToBool(appSetting('app_registration'), true);
}

/**
 * Feature flag: allow frontend telemetry events.
 */
function frontendTelemetryEnabled(): bool
{
    return settingToBool(appSetting('frontend_telemetry_enabled'), false);
}

/**
 * Frontend telemetry sample rate normalized to 0..1.
 */
function frontendTelemetrySampleRate(): float
{
    $value = appSetting('frontend_telemetry_sample_rate');
    if ($value === null || trim($value) === '') {
        return 0.2;
    }

    $rate = is_numeric($value) ? (float) $value : NAN;
    if (!is_finite($rate) || $rate < 0 || $rate > 1) {
        return 0.2;
    }

    return $rate;
}

/**
 * Allowed frontend telemetry events as canonical short keys.
 *
 * @return list<string>
 */
function frontendTelemetryAllowedEvents(): array
{
    $allowed = ['warn_once', 'ajax_error'];
    $value = appSetting('frontend_telemetry_allowed_events');
    if ($value === null || trim($value) === '') {
        return $allowed;
    }

    $items = preg_split('/[\s,]+/', strtolower(trim($value))) ?: [];
    $normalized = array_values(array_unique(array_filter(
        array_map(
            static fn ($entry): string => trim((string) $entry),
            $items
        ),
        static fn ($entry): bool => in_array($entry, $allowed, true)
    )));

    if ($normalized === []) {
        return $allowed;
    }

    sort($normalized, SORT_STRING);
    return $normalized;
}

/**
 * Sort array items by 'description' case-insensitively.
 */
function sortByDescription(array &$items): void
{
    usort(
        $items,
        static fn ($a, $b) =>
        strcasecmp((string) ($a['description'] ?? ''), (string) ($b['description'] ?? ''))
    );
}

/**
 * Decide whether any admin panel capability is available in layout auth.
 *
 * @param array<string, mixed> $layoutAuth
 */
function layoutHasAdminPanel(array $layoutAuth): bool
{
    // Collect capability keys contributed by modules — these are non-admin
    // capabilities that should not trigger the admin panel visibility.
    $moduleCapabilities = [];
    try {
        /** @var \MintyPHP\App\Module\ModuleRegistry $registry */
        $registry = app(\MintyPHP\App\Module\ModuleRegistry::class);
        foreach ($registry->getUiSlots() as $contributions) {
            foreach ($contributions as $contribution) {
                $perm = is_array($contribution) ? trim((string) ($contribution['permission'] ?? '')) : '';
                if ($perm !== '') {
                    $moduleCapabilities[$perm] = true;
                }
            }
        }
    } catch (\Throwable) {
        // fail-open: if module registry is not available, skip module capabilities
    }

    $capabilityKeys = array_keys(\MintyPHP\Service\Access\UiCapabilityMap::LAYOUT);
    foreach ($capabilityKeys as $key) {
        if (isset($moduleCapabilities[$key])) {
            continue;
        }
        if (!empty($layoutAuth[$key])) {
            return true;
        }
    }

    return false;
}

/**
 * Reserved top-level keys in layout navigation context that modules must not override.
 *
 * @return list<string>
 */
function appLayoutNavReservedKeys(): array
{
    return [
        'hasAdminPanel',
        'moduleSlots',
        'currentTenant',
        'availableTenants',
        'tenantQueryParam',
        'tenantAvatar',
        'csrfKey',
        'csrfToken',
    ];
}

/**
 * Merge one module layout-provider payload into layout navigation context.
 *
 * Provider keys are contract-validated and must be namespaced (`module.key`).
 *
 * @param array<string, mixed> $layoutNav
 * @param array<string, mixed> $providerData
 * @return array<string, mixed>
 */
function appMergeLayoutNavProviderData(array $layoutNav, array $providerData, string $providerClass): array
{
    $reserved = array_fill_keys(appLayoutNavReservedKeys(), true);

    foreach ($providerData as $rawKey => $value) {
        $key = trim((string) $rawKey);
        if ($key === '') {
            throw new \RuntimeException(
                "Layout context provider '{$providerClass}' returned an empty top-level key."
            );
        }
        if (isset($reserved[$key])) {
            throw new \RuntimeException(
                "Layout context provider '{$providerClass}' must not override reserved layout key '{$key}'."
            );
        }
        if (array_key_exists($key, $layoutNav)) {
            throw new \RuntimeException(
                "Layout context provider '{$providerClass}' collides on existing layout key '{$key}'."
            );
        }
        if (!preg_match('/^[a-z0-9]+[a-z0-9._-]*$/', $key) || !str_contains($key, '.')) {
            throw new \RuntimeException(
                "Layout context provider '{$providerClass}' key '{$key}' must be namespaced (e.g. '<module_id>.data')."
            );
        }
        $layoutNav[$key] = $value;
    }

    return $layoutNav;
}

/**
 * Build precomputed layout navigation context for templates.
 *
 * @param array<string, mixed> $layoutAuth
 * @param array<string, mixed> $session
 * @param array<string, mixed> $query
 * @return array<string, mixed>
 */
function appBuildLayoutNavContext(array $layoutAuth, array $session, array $query): array
{
    $currentTenant = is_array($session['current_tenant'] ?? null) ? $session['current_tenant'] : null;
    $availableTenants = is_array($session['available_tenants'] ?? null) ? $session['available_tenants'] : [];
    $tenantUuid = trim((string) ($currentTenant['uuid'] ?? ''));
    $tenantName = trim((string) ($currentTenant['description'] ?? ''));

    $tenantQueryParam = '';
    if (count($availableTenants) > 1 && $tenantUuid !== '') {
        $tenantQueryParam = '?tenant=' . urlencode($tenantUuid);
    }

    $tenantHasAvatar = false;
    if ($tenantUuid !== '' && class_exists(\MintyPHP\Service\Tenant\TenantAvatarService::class)) {
        $tenantHasAvatar = app(\MintyPHP\Service\Tenant\TenantAvatarService::class)->hasAvatar($tenantUuid);
    }

    $csrfKey = \MintyPHP\Session::$csrfSessionKey;
    $csrfToken = (string) ($session[$csrfKey] ?? '');

    // 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,
        'tenantAvatar' => [
            'uuid' => $tenantUuid,
            'name' => $tenantName,
            'hasAvatar' => $tenantHasAvatar,
        ],
        '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);
    } catch (\Throwable) {
        // fail-open: if module registry is not available, skip module providers
        return $layoutNav;
    }

    $container = $GLOBALS['minty_app_container'] ?? null;
    if (!$container instanceof \MintyPHP\App\AppContainer) {
        return $layoutNav;
    }

    foreach ($moduleRegistry->getLayoutContextProviders() as $providerClass) {
        $provider = \MintyPHP\App\Module\ModuleClassResolver::resolve($container, $providerClass);
        if ($provider instanceof \MintyPHP\App\Module\Contracts\LayoutContextProvider) {
            $providerData = $provider->provide($session, $container);
            $layoutNav = appMergeLayoutNavProviderData($layoutNav, $providerData, $providerClass);
        }
    }

    return $layoutNav;
}