feat: release candidate for v 12.5.0

composer.json

@@ -87,7 +87,10 @@
                 "Unusualify\\Modularous\\Providers\\ModularousProvider"
             ],
             "aliases": {
-                "ModularousVite": "Unusualify\\Modularous\\Facades\\ModularousVite"
+                "ModularousVite": "Unusualify\\Modularous\\Facades\\ModularousVite",
+                "SystemSettings": "Unusualify\\Modularous\\Facades\\SystemSettings",
+                "CmsSettings": "Unusualify\\Modularous\\Facades\\CmsSettings",
+                "SiteSettings": "Unusualify\\Modularous\\Facades\\SiteSettings"
             }
         },
         "branch-alias": {
@@ -146,11 +149,11 @@
         ],
         "test:fast:coverage": [
             "@test-clean",
-            "bin/with-coverage-driver paratest --processes=2 --stop-on-defect"
+            "bin/with-coverage-driver paratest --processes=4 --stop-on-defect"
         ],
         "test:fast:coverage:html": [
             "@test-clean",
-            "COVERAGE_MEMORY_LIMIT=-1 bin/with-coverage-driver paratest -c phpunit.coverage-html.xml --processes=2 --stop-on-defect"
+            "bin/with-coverage-driver paratest -c phpunit.coverage-html.xml --processes=4 --stop-on-defect"
         ],
         "test:brokers": "vendor/bin/phpunit --stop-on-defect --no-coverage tests/Brokers",
         "test:events": "vendor/bin/phpunit --stop-on-defect --no-coverage tests/Events",
@@ -194,6 +197,7 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "config": {
+        "process-timeout": 300,
         "sort-packages": true,
         "preferred-install": "dist",
         "optimize-autoloader": true,

config/merges/cms_seo.php

@@ -7,6 +7,7 @@
 use Modules\Cms\Services\CmsAdminWarnings;
 use Modules\Cms\Services\CmsSiteSeoSettingsService;
 use Modules\Cms\Support\CmsPublicSeo;
+use Modules\SystemSetting\Support\MigrateRobotsTxtFromSiteSetting;
 use Unusualify\Modularous\Entities\Traits\Core\HasScopes;
 
 return [
@@ -32,19 +33,23 @@
      * Global robots.txt (served at GET /robots.txt when route enabled).
      *
      * @see RobotsTxtController
+     * @see CmsSiteSeoSettingsService
      */
     'robots' => [
         'route_enabled' => env('MODULAROUS_CMS_ROBOTS_TXT_ROUTE_ENABLED', true),
         'global_robots_txt' => env('MODULAROUS_CMS_SEO_GLOBAL_ROBOTS_TXT', ''),
         /**
-         * When true, GET /robots.txt prefers {@see CmsSiteSeoSettingsService} (um_cms_site_settings).
+         * When true, GET /robots.txt prefers {@see CmsSiteSeoSettingsService}
+         * ({@see \Unusualify\Modularous\Facades\SiteSettings} → CmsSettings with SystemSettings fallback).
          * When false, only env/config {@code global_robots_txt} is used (legacy / headless deploys).
          */
-        'use_site_settings' => env('MODULAROUS_CMS_SEO_ROBOTS_USE_SITE_SETTINGS', true),
+        'use_system_settings' => env('MODULAROUS_CMS_SEO_ROBOTS_USE_SYSTEM_SETTINGS', env('MODULAROUS_CMS_SEO_ROBOTS_USE_SITE_SETTINGS', true)),
         /**
-         * Composite key for the global robots.txt body row (must match unique index on site_settings).
+         * Legacy KV row keys used only by {@see MigrateRobotsTxtFromSiteSetting}.
+         *
+         * @deprecated Robots.txt is stored on SystemSetting General / Cms SiteSetting (IsSingular).
          */
-        'site_setting' => [
+        'legacy_site_setting' => [
             'group_key' => env('MODULAROUS_CMS_SEO_ROBOTS_SITE_GROUP', 'seo'),
             'key' => env('MODULAROUS_CMS_SEO_ROBOTS_SITE_KEY', 'global_robots_txt'),
             'locale' => env('MODULAROUS_CMS_SEO_ROBOTS_SITE_LOCALE', '*'),

config/merges/cms_settings.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'cache_ttl' => (int) env('MODULAROUS_CMS_SETTINGS_CACHE_TTL', env('MODULAROUS_SYSTEM_SETTINGS_CACHE_TTL', 3600)),
+    'sensitive_keys' => [
+        'smtp.password',
+    ],
+];

config/merges/input_types.php

@@ -3,6 +3,24 @@
 use Camroncade\Timezone\Timezone;
 
 return [
+    '@collapsible_wrap' => [
+        'type' => 'wrap',
+        'typeInt' => 'ue-collapsible',
+        'typeIntModelValue' => false,
+        'typeIntTitle' => 'Wrap',
+        'noLabel' => true,
+        'bordered' => true,
+        'col' => ['cols' => 12,'sm' => 12,'md' => 12,'lg' => 12,'xl' => 12],
+    ],
+    '@collapsible_group' => [
+        'type' => 'group',
+        'typeInt' => 'ue-collapsible',
+        'typeIntModelValue' => false,
+        'typeIntTitle' => 'Group',
+        'noLabel' => true,
+        'bordered' => true,
+        'col' => ['cols' => 12,'sm' => 12,'md' => 12,'lg' => 12,'xl' => 12],
+    ],
     '_language' => [
         'type' => 'select',
         'name' => 'language',

config/merges/system_settings.php

@@ -0,0 +1,45 @@
+<?php
+
+return [
+    'name' => 'SystemSetting',
+    'system_prefix' => true,
+    'group' => 'system',
+    'headline' => 'System Settings',
+    'cache_ttl' => (int) env('MODULAROUS_SYSTEM_SETTINGS_CACHE_TTL', 3600),
+    /**
+     * Fallback when SystemSettings `analytics.enabled` is unset in the DB.
+     * Staging should leave DB off (or unset) so this stays false.
+     * Prod: set analytics.enabled=true in System Settings (or MODULAROUS_ANALYTICS_ENABLED=true as seed default).
+     */
+    'analytics_enabled_default' => (bool) env('MODULAROUS_ANALYTICS_ENABLED', false),
+    /**
+     * When true, smtp.* from System Settings overrides config/mail.php.
+     * Prefer .env MAIL_* unless you explicitly need CMS-managed SMTP.
+     */
+    'mail_override_enabled' => (bool) env('MODULAROUS_SYSTEM_SETTINGS_MAIL_OVERRIDE', false),
+    'sensitive_keys' => [
+        'smtp.password',
+    ],
+    'extra_inputs' => [],
+    'input_overrides' => [],
+    'hidden_inputs' => [],
+    'input_aliases' => [
+        '@system_social_links' => [
+            'type' => 'json-repeater',
+            'name' => 'social',
+            'label' => 'Social Links',
+            'default' => [],
+            'draggable' => true,
+            'orderKey' => 'position',
+            'noHeaders' => true,
+            'collapsible' => true,
+            'collapsibleTitleField' => 'platform',
+            'collapsibleDefaultOpen' => false,
+            'schema' => [
+                ['name' => 'platform', 'type' => 'text', 'label' => 'Platform', 'rules' => 'required'],
+                ['name' => 'url', 'type' => 'text', 'label' => 'URL', 'rules' => 'required'],
+                ['name' => 'icon', 'type' => 'image', 'label' => 'Icon', 'rules' => 'nullable'],
+            ],
+        ]
+    ],
+];

docs/src/pages/system-reference/backend/facades/cms-settings.md

@@ -0,0 +1,52 @@
+---
+sidebarPos: 2
+sidebarTitle: CmsSettings
+---
+
+# CmsSettings
+
+**Facade**: `Unusualify\Modularous\Facades\CmsSettings`  
+**Accessor**: `cms.settings`  
+**Underlying**: `Modules\Cms\Services\CmsSettingsService`  
+**Model**: `Modules\Cms\Entities\SiteSetting` (`IsSingular`)
+
+Frontend/CMS-facing settings singleton. No System fallback — use [`SiteSettings`](./site-settings) when empty CMS keys should fall through to System. Full guide: [Settings Services](/system-reference/backend/services/settings/overview).
+
+## Sections
+
+`site`, `social`, `contact`, `seo` only.
+
+`smtp`, `analytics`, and `locale` are **not** editable on `SiteSetting` — use [`SystemSettings`](./system-settings).
+
+## Methods
+
+Shared singular API — see [Shared API](/system-reference/backend/services/settings/overview#shared-api).
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `get` / `value` | `(string $key, mixed $default = null, ?string $locale = null): mixed` | Dot-path read with locale / media-leaf expansion |
+| `first` | `(string $key, mixed $default = null, ?string $locale = null): mixed` | First list element when applicable |
+| `all` | `(?string $locale = null): array` | Locale-resolved section tree |
+| `has` | `(string $key): bool` | Key exists in snapshot |
+| `filled` | `(string $key, ?string $locale = null): bool` | Resolved value is non-empty |
+| `set` | `(string $key, mixed $value): void` | Persist + forget cache |
+| `forgetCache` | `(): void` | Clear cached snapshot |
+| `snapshot` | `(): array` | Raw cached sections |
+
+## Usage
+
+```php
+use Unusualify\Modularous\Facades\CmsSettings;
+
+CmsSettings::set('site.name', 'Public site name');
+$tagline = CmsSettings::get('site.tagline');
+
+if (! CmsSettings::filled('seo.default_meta_title')) {
+    // CMS empty — SiteSettings::forFrontend() would fall back to System
+}
+```
+
+## Notes
+
+- Seed empty CMS from System with [`DuplicateSystemSettingsToCmsSettings`](/system-reference/backend/services/settings/overview#duplicatesystemsettingstocmssettings).
+- Cache key: `cms_settings.snapshot` (`modularous.cms_settings.cache_ttl`).

docs/src/pages/system-reference/backend/facades/overview.md

@@ -5,7 +5,7 @@ sidebarTitle: Overview
 
 # Facades
 
-Modularous registers 18 Laravel facades, all under the `Unusualify\Modularous\Facades\` namespace. Each facade is an alias to a bound service container entry, providing static-style access to the underlying service class.
+Modularous registers 21 Laravel facades, all under the `Unusualify\Modularous\Facades\` namespace. Each facade is an alias to a bound service container entry, providing static-style access to the underlying service class.
 
 ## Overview
 
@@ -28,8 +28,13 @@ Modularous registers 18 Laravel facades, all under the `Unusualify\Modularous\Fa
 | [Register](./register) | `auth.register` | `RegisterBrokerManager` |
 | [HostRouting](./host-routing) | `unusualify.hosting` | `Support\HostRouting` |
 | [HostRoutingRegistrar](./host-routing-registrar) | `unusualify.hostRouting` | `Support\HostRouting` |
+| [SystemSettings](./system-settings) | `system.settings` | `Modules\SystemSetting\Services\SystemSettingsService` |
+| [CmsSettings](./cms-settings) | `cms.settings` | `Modules\Cms\Services\CmsSettingsService` |
+| [SiteSettings](./site-settings) | `site.settings` | `Modules\Cms\Services\SiteSettingsService` |
 | [UFinder](./u-finder) *(deprecated)* | `Finder::class` | `Support\Finder` |
 
+Settings facades share one API and differ by backing store / context routing — see [Settings Services](/system-reference/backend/services/settings/overview).
+
 ## Usage Pattern
 
 All Modularous facades follow standard Laravel facade usage:

docs/src/pages/system-reference/backend/facades/site-settings.md

@@ -0,0 +1,68 @@
+---
+sidebarPos: 19
+sidebarTitle: SiteSettings
+---
+
+# SiteSettings
+
+**Facade**: `Unusualify\Modularous\Facades\SiteSettings`  
+**Accessor**: `site.settings`  
+**Underlying**: `Modules\Cms\Services\SiteSettingsService`
+
+Context-aware router over CMS and System settings. Prefer this facade in public layouts and when code may run in both frontend and panel contexts. Full guide: [Settings Services](/system-reference/backend/services/settings/overview).
+
+| Context | Behaviour |
+|---------|-----------|
+| Frontend (non-panel HTTP) | [`CmsSettings`](./cms-settings) with fallback to [`SystemSettings`](./system-settings) |
+| Backend / panel / console | [`SystemSettings`](./system-settings) only |
+
+## Methods
+
+### Context
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `forFrontend` | `(): SiteSettingsService` | Force CMS layer + System fallback |
+| `forBackend` | `(): SiteSettingsService` | Force System only |
+| `forCms` | `(): SiteSettingsService` | Alias of `forFrontend()` |
+| `forSystem` | `(): SiteSettingsService` | Alias of `forBackend()` |
+| `usesCmsLayer` | `(): bool` | Whether the CMS layer is active |
+| `cms` | `(): CmsSettingsService` | Underlying CMS service |
+| `system` | `(): SystemSettingsService` | Underlying System service |
+
+### Shared read/write
+
+Same signatures as the singular services — see [Shared API](/system-reference/backend/services/settings/overview#shared-api): `get`, `value`, `first`, `all`, `has`, `filled`, `set`, `forgetCache`, `snapshot`.
+
+On the CMS layer, `set` writes to CMS only; `forgetCache` clears both layers.
+
+## Usage
+
+```blade
+<img src="{{ SiteSettings::value('site.logo.frontend') }}" alt="{{ SiteSettings::get('site.name') }}">
+```
+
+```php
+use Unusualify\Modularous\Facades\SiteSettings;
+
+// Auto: frontend → CMS+fallback, panel/console → System
+$name = SiteSettings::get('site.name', config('app.name'));
+
+// Explicit
+$public = SiteSettings::forFrontend()->get('seo.robots_txt');
+SiteSettings::forBackend()->set('seo.robots_txt', $body);
+
+// System-only keys still resolve on frontend via fallback
+$gtm = SiteSettings::forFrontend()->get('analytics.gtm_id');
+```
+
+```php
+public function __construct(
+    protected \Modules\Cms\Services\SiteSettingsService $siteSettings,
+) {}
+```
+
+## Notes
+
+- Analytics snippets: [`AnalyticsScripts`](/system-reference/backend/services/settings/overview#analyticsscripts) (reads through this router).
+- Empty CMS leaves do not overwrite System values in `all()` / `snapshot()`.

docs/src/pages/system-reference/backend/facades/system-settings.md

@@ -0,0 +1,53 @@
+---
+sidebarPos: 20
+sidebarTitle: SystemSettings
+---
+
+# SystemSettings
+
+**Facade**: `Unusualify\Modularous\Facades\SystemSettings`  
+**Accessor**: `system.settings`  
+**Underlying**: `Modules\SystemSetting\Services\SystemSettingsService`  
+**Model**: `Modules\SystemSetting\Entities\General` (`IsSingular`)
+
+Backend / system source of truth for global settings. Full usage guide: [Settings Services](/system-reference/backend/services/settings/overview).
+
+## Sections
+
+`site`, `social`, `contact`, `seo`, `smtp`, `analytics`, `locale`
+
+## Methods
+
+Shared singular API — see [Shared API](/system-reference/backend/services/settings/overview#shared-api).
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `get` / `value` | `(string $key, mixed $default = null, ?string $locale = null): mixed` | Dot-path read with locale / media-leaf expansion |
+| `first` | `(string $key, mixed $default = null, ?string $locale = null): mixed` | First list element when applicable |
+| `all` | `(?string $locale = null): array` | Locale-resolved section tree |
+| `has` | `(string $key): bool` | Key exists in snapshot |
+| `filled` | `(string $key, ?string $locale = null): bool` | Resolved value is non-empty |
+| `set` | `(string $key, mixed $value): void` | Persist + forget cache |
+| `forgetCache` | `(): void` | Clear cached snapshot |
+| `snapshot` | `(): array` | Raw cached sections |
+
+## Usage
+
+```php
+use Unusualify\Modularous\Facades\SystemSettings;
+
+$host = SystemSettings::get('smtp.host');
+SystemSettings::set('locale.timezone', 'Europe/Amsterdam');
+
+$favicon = SystemSettings::value('site.favicon.original');
+```
+
+```blade
+<link rel="icon" href="{{ SystemSettings::value('site.favicon.original') }}">
+```
+
+## Notes
+
+- Prefer `SystemSettings` (or `SiteSettings::forBackend()`) for SMTP, analytics, and locale — those sections are not on `SiteSetting`.
+- Optional mail override: [ApplySmtpMailConfig](/system-reference/backend/services/settings/overview#applysmtpmailconfig) via `MODULAROUS_SYSTEM_SETTINGS_MAIL_OVERRIDE`.
+- Cache key: `system_settings.snapshot` (`modularous.system_settings.cache_ttl`).

docs/src/pages/system-reference/backend/facades/u-finder.md

@@ -1,5 +1,5 @@
 ---
-sidebarPos: 19
+sidebarPos: 22
 sidebarTitle: UFinder (deprecated)
 ---
 

docs/src/pages/system-reference/backend/facades/utm.md

@@ -1,5 +1,5 @@
 ---
-sidebarPos: 18
+sidebarPos: 21
 sidebarTitle: Utm
 ---
 

docs/src/pages/system-reference/backend/overview.md

@@ -235,9 +235,11 @@ Events fire at lifecycle boundaries (model created/updated, user registered, sta
 
 **Directory**: `src/Facades/` · **Namespace**: `Unusualify\Modularous\Facades`
 
-18 Laravel facades providing static-style access to bound services. Each facade aliases a container entry to a concrete service class.
+21 Laravel facades providing static-style access to bound services. Each facade aliases a container entry to a concrete service class.
 
-**Selected facades**: [`Coverage`](/system-reference/backend/facades/coverage), [`CurrencyExchange`](/system-reference/backend/facades/currency-exchange), [`Filepond`](/system-reference/backend/facades/filepond), [`HostRouting`](/system-reference/backend/facades/host-routing), [`MigrationBackup`](/system-reference/backend/facades/migration-backup), [`Modularous`](/system-reference/backend/facades/modularous), [`ModularousCache`](/system-reference/backend/facades/modularous-cache), [`ModularousRoutes`](/system-reference/backend/facades/modularous-routes), [`ModularousVite`](/system-reference/backend/facades/modularous-vite), [`Navigation`](/system-reference/backend/facades/navigation), [`Redirect`](/system-reference/backend/facades/redirect), [`Register`](/system-reference/backend/facades/register), [`RelationshipGraph`](/system-reference/backend/facades/relationship-graph), [`Utm`](/system-reference/backend/facades/utm).
+**Selected facades**: [`Coverage`](/system-reference/backend/facades/coverage), [`CurrencyExchange`](/system-reference/backend/facades/currency-exchange), [`Filepond`](/system-reference/backend/facades/filepond), [`HostRouting`](/system-reference/backend/facades/host-routing), [`MigrationBackup`](/system-reference/backend/facades/migration-backup), [`Modularous`](/system-reference/backend/facades/modularous), [`ModularousCache`](/system-reference/backend/facades/modularous-cache), [`ModularousRoutes`](/system-reference/backend/facades/modularous-routes), [`ModularousVite`](/system-reference/backend/facades/modularous-vite), [`Navigation`](/system-reference/backend/facades/navigation), [`Redirect`](/system-reference/backend/facades/redirect), [`Register`](/system-reference/backend/facades/register), [`RelationshipGraph`](/system-reference/backend/facades/relationship-graph), [`SiteSettings`](/system-reference/backend/facades/site-settings), [`SystemSettings`](/system-reference/backend/facades/system-settings), [`CmsSettings`](/system-reference/backend/facades/cms-settings), [`Utm`](/system-reference/backend/facades/utm).
+
+Settings deep-dive: [Settings Services](/system-reference/backend/services/settings/overview).
 
 → [Full Facades reference](/system-reference/backend/facades/overview)
 
@@ -446,6 +448,7 @@ Bound in the service container; injected via constructor or accessed through the
 | **Cache concerns** | CacheHelpers, CacheInvalidation, CacheTags | [Cache Concerns →](/system-reference/backend/services/cache-concerns/overview) |
 | **Core services** | Assets, BroadcastManager, Connector, CoverageService, CurrencyExchangeService, FilepondManager, FileTranslation, MessageStage, MigrationBackup, ModularousCacheService, RedirectService, Translation, UtmParameters | [Services →](/system-reference/backend/services/overview) |
 | **Currency** | NullCurrencyProvider, SystemPricingCurrencyProvider | [Currency →](/system-reference/backend/services/currency/overview) |
+| **Settings** | AbstractSingularSettingsService, SystemSettingsService, CmsSettingsService, SiteSettingsService | [Settings →](/system-reference/backend/services/settings/overview) |
 | **FileLibrary** | Disk, FileService | [FileLibrary →](/system-reference/backend/services/file-library/overview) |
 | **MediaLibrary** | Glide, Imgix, Local, TwicPics drivers | [MediaLibrary →](/system-reference/backend/services/media-library/overview) |
 | **Uploader** | SignAzureUpload, SignS3Upload, SignUploadListener | [Uploader →](/system-reference/backend/services/uploader/overview) |

docs/src/pages/system-reference/backend/services/overview.md

@@ -25,3 +25,4 @@ The `src/Services/` directory contains the top-level service classes that power
 | [CurrencyExchangeService](/system-reference/backend/services/currency-exchange-service) | `CurrencyExchange` | Fetches and caches live exchange rates |
 | [CacheRelationshipGraph](/system-reference/backend/services/cache-relationship-graph) | — | Builds a model→module-route dependency graph for targeted cache invalidation |
 | [CoverageService](/system-reference/backend/services/coverage-service) | `coverage.service` | Parses Clover XML reports; generates coverage reports and PR checks |
+| [Settings](/system-reference/backend/services/settings/overview) | `SystemSettings` / `CmsSettings` / `SiteSettings` | Singular system & CMS settings (dot paths, locale, media leaves, context routing) |