Add unified config system

.claude/settings.local.json

@@ -8,7 +8,8 @@
       "Bash(vendor/bin/ecs:*)",
       "Bash(vendor/bin/phpstan:*)",
       "Bash(vendor/bin/phpunit:*)",
-      "Bash(vendor/bin/rector process:*)"
+      "Bash(vendor/bin/rector process:*)",
+      "Bash(vendor/bin/rector)"
     ]
   }
 }

docs/configuration/index.md

@@ -0,0 +1,374 @@
+# Configuration
+
+SolidWorx Platform is configured through a single `platform.yaml` (or `platform.php`) file placed in your project root — the same directory that contains `composer.json`.
+
+All platform options live under a single `platform:` key, which means one file, one place to look, and no guessing which bundle owns which setting.
+
+---
+
+## Quick start
+
+Create `platform.yaml` in your project root:
+
+```yaml
+# platform.yaml
+platform:
+  name: 'My App'
+```
+
+That is the minimum viable configuration. Every option has a sensible default, so you only need to set what differs from those defaults.
+
+---
+
+## Supported file formats
+
+| File | Format | Notes |
+|------|--------|-------|
+| `platform.yaml` | YAML | Recommended for most projects |
+| `platform.yml` | YAML | Alternative extension |
+| `platform.json` | JSON | Useful when config is generated by a tool |
+| `platform.php` | PHP | Use the [fluent builder](#php-fluent-builder) for IDE-assisted config |
+
+Only one file may be present at a time. If multiple files are found the platform throws an error at boot.
+
+### Overriding the file location
+
+Set the `PLATFORM_CONFIG_FILE` environment variable to an absolute path to load config from a non-standard location:
+
+```bash
+PLATFORM_CONFIG_FILE=/etc/myapp/platform.yaml php bin/console cache:clear
+```
+
+This is useful in Docker environments where the config file lives outside the project directory.
+
+---
+
+## IDE autocomplete
+
+A `platform-schema.json` file is distributed with the package. Reference it at the top of your `platform.yaml` to get full autocompletion, hover documentation, and inline validation in editors that support YAML Language Server (VS Code, PhpStorm, etc.):
+
+```yaml
+# yaml-language-server: $schema=./vendor/solidworx/platform/platform-schema.json
+platform:
+  name: 'My App'
+```
+
+### Regenerating the schema
+
+If you have made local changes to the platform or need to refresh the schema after a version upgrade, run:
+
+```bash
+php bin/console platform:generate-schema
+```
+
+This writes `platform-schema.json` to your project root. Commit the file alongside your configuration so the schema stays in sync with the installed version.
+
+To write to a custom path:
+
+```bash
+php bin/console platform:generate-schema --output=config/platform-schema.json
+```
+
+---
+
+## Full configuration reference
+
+The sections below document every available option. Options marked **required** have no default and must be set. All others are optional and show their default value.
+
+### Core (`platform`)
+
+These options apply globally and are owned by the Platform bundle.
+
+```yaml
+platform:
+  # Human-readable name of your application.
+  # Used as the application title and in email subjects (e.g. 2FA emails).
+  # Default: 'SolidWorx Platform'
+  name: 'My App'
+
+  # Application version string. Informational only.
+  # Default: '1.0.0'
+  version: '1.0.0'
+```
+
+---
+
+### Security (`platform.security`)
+
+```yaml
+platform:
+  security:
+    two_factor:
+      # Whether to enable two-factor authentication.
+      # When true, the SchebTwoFactorBundle is registered automatically
+      # and the 2FA routes and Twig components become active.
+      # Default: false
+      enabled: false
+
+      # The Twig template that wraps 2FA pages (TOTP and email codes).
+      # The template must expose a `content` block where the 2FA form is rendered.
+      # Required when `enabled: true`.
+      base_template: '@App/layout/base.html.twig'
+```
+
+**Example — enabling 2FA:**
+
+```yaml
+platform:
+  name: 'My App'
+  security:
+    two_factor:
+      enabled: true
+      base_template: '@App/layout/base.html.twig'
+```
+
+When 2FA is enabled the platform automatically:
+- Registers `SchebTwoFactorBundle`
+- Configures TOTP and email-based second factors
+- Adds trusted-device support (30-day lifetime)
+- Registers 2FA routes and access control rules
+
+---
+
+### Doctrine (`platform.doctrine`)
+
+```yaml
+platform:
+  doctrine:
+    types:
+      # Whether to override Doctrine's datetime types with UTC-aware equivalents.
+      # When true, all DATETIME_IMMUTABLE and DATETIMETZ_IMMUTABLE columns are
+      # stored and read in UTC, preventing timezone drift across environments.
+      # Default: true
+      enable_utc_date: true
+```
+
+---
+
+### Models (`platform.models`)
+
+Override the default platform entities with your own application entities. This is the mechanism by which the platform resolves the user entity throughout the security layer.
+
+```yaml
+platform:
+  models:
+    # Fully-qualified class name of the User entity.
+    # Must implement the Symfony UserInterface.
+    # Default: SolidWorx\Platform\PlatformBundle\Model\User
+    user: App\Entity\User
+```
+
+---
+
+### SaaS (`platform.saas`)
+
+The `saas` section is only required when `SolidWorxPlatformSaasBundle` is registered in your application. All options in this section except those with defaults are **required**.
+
+```yaml
+platform:
+  saas:
+
+    doctrine:
+      subscriptions:
+        # Fully-qualified class name of your Subscription entity.
+        # The entity must implement SubscribableInterface.
+        # Required.
+        entity: App\Entity\Subscription
+
+      db_schema:
+        table_names:
+          # Override the database table names for the SaaS entities.
+          # Defaults shown below — omit any you do not need to change.
+          plan: plans
+          subscription: subscriptions
+          subscription_log: subscription_logs
+          plan_feature: plan_features
+
+    payment:
+      # The Symfony route name to redirect to after a successful payment.
+      # Required.
+      return_route: app_payment_return
+
+    integration:
+      lemon_squeezy:
+        # Whether the LemonSqueezy payment integration is active.
+        # Default: false
+        enabled: false
+
+        # LemonSqueezy API credentials. Using %env()% placeholders is
+        # strongly recommended over hard-coded values.
+        api_key: '%env(LEMON_SQUEEZY_API_KEY)%'
+        webhook_secret: '%env(LEMON_SQUEEZY_WEBHOOK_SECRET)%'
+        store_id: '%env(LEMON_SQUEEZY_STORE_ID)%'
+
+    # Named feature flags available on subscription plans.
+    # Each entry defines the type, default value, and an optional description.
+    features:
+      api_calls:
+        type: integer       # boolean | integer | string | array
+        default: 1000
+        description: 'Maximum API calls per billing period'
+
+      file_uploads:
+        type: boolean
+        default: false
+        description: 'Whether the plan allows file uploads'
+
+      allowed_users:
+        type: integer
+        default: 1
+        description: 'Number of team members allowed on the plan'
+```
+
+**Feature types:**
+
+| `type` | Default value format |
+|--------|---------------------|
+| `boolean` | `true` or `false` |
+| `integer` | Any integer (e.g. `100`, `-1` for unlimited) |
+| `string` | Any string value |
+| `array` | A YAML sequence (list) |
+
+---
+
+### UI (`platform.ui`)
+
+The `ui` section applies when `SolidWorxPlatformUiBundle` is registered.
+
+```yaml
+platform:
+  ui:
+    # The icon library to load.
+    # Default: 'tabler'
+    icon_pack: tabler
+
+    templates:
+      # The Twig template used as the outer HTML shell for all pages.
+      # Your template must expose a `content` block.
+      # Default: '@Ui/Layout/base.html.twig'
+      base: '@App/layout/base.html.twig'
+
+      # The Twig template rendered for the login page.
+      # Default: '@Ui/Security/login.html.twig'
+      login: '@App/security/login.html.twig'
+```
+
+---
+
+## A complete example
+
+The following shows a fully populated `platform.yaml` for a typical SaaS application:
+
+```yaml
+# yaml-language-server: $schema=./platform-schema.json
+platform:
+  name: 'Acme SaaS'
+  version: '2.0.0'
+
+  security:
+    two_factor:
+      enabled: true
+      base_template: '@App/layout/base.html.twig'
+
+  doctrine:
+    types:
+      enable_utc_date: true
+
+  models:
+    user: App\Entity\User
+
+  saas:
+    doctrine:
+      subscriptions:
+        entity: App\Entity\Subscription
+      db_schema:
+        table_names:
+          plan: plans
+          subscription: subscriptions
+          subscription_log: subscription_logs
+          plan_feature: plan_features
+
+    payment:
+      return_route: app_payment_success
+
+    integration:
+      lemon_squeezy:
+        enabled: true
+        api_key: '%env(LEMON_SQUEEZY_API_KEY)%'
+        webhook_secret: '%env(LEMON_SQUEEZY_WEBHOOK_SECRET)%'
+        store_id: '%env(LEMON_SQUEEZY_STORE_ID)%'
+
+    features:
+      api_calls:
+        type: integer
+        default: 500
+        description: 'API calls per billing period'
+      advanced_reports:
+        type: boolean
+        default: false
+        description: 'Access to advanced reporting'
+      team_members:
+        type: integer
+        default: 1
+        description: 'Allowed team members'
+
+  ui:
+    icon_pack: tabler
+    templates:
+      base: '@App/layout/base.html.twig'
+      login: '@App/security/login.html.twig'
+```
+
+---
+
+## PHP fluent builder
+
+If you prefer PHP over YAML — or want type-safe, IDE-navigable config — rename the file to `platform.php` and return an array from the builder:
+
+```php
+<?php
+// platform.php
+
+use SolidWorx\Platform\PlatformBundle\Config\Builder\PlatformConfigBuilder;
+use SolidWorx\Platform\SaasBundle\Config\Builder\SaasConfigBuilder;
+use SolidWorx\Platform\UiBundle\Config\Builder\UiConfigBuilder;
+
+return PlatformConfigBuilder::create()
+    ->name('Acme SaaS')
+    ->version('2.0.0')
+    ->security()
+        ->twoFactor()
+            ->enabled(true)
+            ->baseTemplate('@App/layout/base.html.twig')
+        ->end()
+    ->end()
+    ->enableUtcDate(true)
+    ->userModel(\App\Entity\User::class)
+    ->withSaasConfig(
+        SaasConfigBuilder::create()
+            ->subscriptionEntity(\App\Entity\Subscription::class)
+            ->payment()
+                ->returnRoute('app_payment_success')
+            ->end()
+            ->lemonSqueezy(
+                apiKey: '%env(LEMON_SQUEEZY_API_KEY)%',
+                webhookSecret: '%env(LEMON_SQUEEZY_WEBHOOK_SECRET)%',
+                storeId: '%env(LEMON_SQUEEZY_STORE_ID)%',
+            )
+            ->feature('api_calls', ['type' => 'integer', 'default' => 500, 'description' => 'API calls per billing period'])
+            ->feature('advanced_reports', ['type' => 'boolean', 'default' => false])
+            ->build()
+    )
+    ->withUiConfig(
+        UiConfigBuilder::create()
+            ->iconPack('tabler')
+            ->baseTemplate('@App/layout/base.html.twig')
+            ->loginTemplate('@App/security/login.html.twig')
+            ->build()
+    )
+    ->build();
+```
+
+The PHP builder produces the same raw array as YAML. No validation occurs at this stage — validation runs during container compilation, just like the YAML path.
+
+> **Note:** `platform.yaml` and `platform.php` cannot coexist. Keep only one format in your project root.

docs/index.md

@@ -4,4 +4,5 @@ Welcome to the SolidWorx Platform documentation. This platform provides the foun
 
 ## Contents
 
+- [Configuration](./configuration/index.md)
 - [Doctrine Types](./doctrine-types/index.md)