folderweb/docs/03-reference/01-configuration.md

# Configuration Reference

FolderWeb uses INI files for configuration. The configuration system follows a simple hierarchy with sensible defaults.

## Configuration Files

```
app/default/config.ini    # Framework defaults (don't modify)
custom/config.ini         # Your overrides (create this)
```

**How it works:**
1. FolderWeb loads `app/default/config.ini`
2. If `custom/config.ini` exists, its values override the defaults
3. Only override what you need—missing values fall back to defaults

## Creating Your Configuration

**custom/config.ini:**

```ini
[languages]
default = "en"
available = "en,no,de"

[plugins]
enabled = "languages,my-custom-plugin"

[site]
title = "My Website"
```

That's it. Only add what you need to change.

## Available Configuration Options

### `[languages]`

Controls multilingual support (requires the `languages` plugin).

```ini
[languages]
default = "en"           # Default language code
available = "en,no,de"   # Comma-separated list of available languages
```

**Values:**
- `default` — Language code used when no language is specified in URL
- `available` — Comma-separated list of language codes (ISO 639-1)

**Example:**
```ini
[languages]
default = "no"
available = "no,en"
```

### `[plugins]`

Controls which plugins are loaded.

```ini
[plugins]
enabled = "languages,analytics,custom-plugin"
```

**Values:**
- `enabled` — Comma-separated list of plugin names (without `.php` extension)

**Plugin loading order:**
1. `app/plugins/global/` — Built-in global plugins
2. `custom/plugins/global/` — Your global plugins
3. `app/plugins/page/` — Built-in page plugins (not yet used)
4. `custom/plugins/page/` — Your page plugins (not yet used)

**Example:**
```ini
[plugins]
enabled = "languages"
```

To disable all plugins, leave the value empty:
```ini
[plugins]
enabled = ""
```

### Custom Sections

Add your own configuration sections for custom plugins:

```ini
[analytics]
tracking_id = "UA-12345678-1"
enabled = true

[social]
twitter = "@myhandle"
github = "myusername"

[api]
endpoint = "https://api.example.com"
key = "secret-key-here"
```

Access in plugins via the `$config` parameter:

```php
Hooks::add(Hook::CONTEXT_READY, function(Context $ctx, array $config) {
    $trackingId = $config['analytics']['tracking_id'] ?? null;
    // Use the config value...
    return $ctx;
});
```

## Default Configuration

Here's what's included in `app/default/config.ini`:

```ini
[languages]
default = "en"
available = "en,no"

[plugins]
enabled = "languages"
```

These values are active unless you override them in `custom/config.ini`.

## Configuration Best Practices

### 1. Only Override What Changes

**Bad:**
```ini
[languages]
default = "en"
available = "en,no"

[plugins]
enabled = "languages"
```

**Good:**
```ini
# Only change the default language
[languages]
default = "no"
```

### 2. Use Comments

```ini
[languages]
default = "no"           # Norwegian site
available = "no,en,de"   # Also support English and German

[plugins]
enabled = "languages,analytics"  # Google Analytics plugin
```

### 3. Keep Secrets Separate

Don't commit API keys and secrets to version control. Use environment-specific config or `.gitignore`:

```ini
[api]
key = "dev-key-here"  # Override in production
```

### 4. Organize by Purpose

```ini
# Multilingual settings
[languages]
default = "en"
available = "en,no"

# Third-party services
[analytics]
enabled = true
tracking_id = "UA-12345678-1"

# Custom features
[reading_time]
words_per_minute = 200
```

## Environment-Specific Configuration

FolderWeb doesn't have built-in environment detection, but you can handle it manually:

**Option 1: Different files**

```bash
# Development
ln -s custom/config.dev.ini custom/config.ini

# Production
ln -s custom/config.prod.ini custom/config.ini
```

**Option 2: Server-side includes**

**custom/config.ini:**
```ini
[languages]
default = "en"
```

**custom/config.prod.ini:**
```ini
[api]
key = "production-key"
```

Load production config in your deployment script:
```bash
cat custom/config.prod.ini >> custom/config.ini
```

**Option 3: Environment variables**

Read from environment variables in a custom plugin:

```php
Hooks::add(Hook::CONTEXT_READY, function(Context $ctx, array $config) {
    // Override config with environment variables
    $apiKey = getenv('API_KEY') ?: ($config['api']['key'] ?? null);
    $ctx->set('api_key', $apiKey);
    return $ctx;
});
```

## Accessing Configuration in Code

Configuration is passed to plugin hooks:

```php
Hooks::add(Hook::CONTEXT_READY, function(Context $ctx, array $config) {
    // Access configuration
    $defaultLang = $config['languages']['default'] ?? 'en';
    $plugins = $config['plugins']['enabled'] ?? '';
    
    // Use it
    $ctx->set('site_lang', $defaultLang);
    
    return $ctx;
});
```

Configuration is **not** directly available in templates. If you need config values in templates, set them via a plugin hook:

```php
Hooks::add(Hook::TEMPLATE_VARS, function(array $vars, Context $ctx) {
    global $config;
    
    $vars['siteTitle'] = $config['site']['title'] ?? 'My Site';
    $vars['socialLinks'] = [
        'twitter' => $config['social']['twitter'] ?? null,
        'github' => $config['social']['github'] ?? null,
    ];
    
    return $vars;
});
```

## Configuration Schema

FolderWeb doesn't enforce a schema—you can add any sections and keys you need. However, these are the recognized built-in options:

| Section | Key | Type | Default | Description |
|---------|-----|------|---------|-------------|
| `languages` | `default` | string | `"en"` | Default language code |
| `languages` | `available` | string | `"en,no"` | Comma-separated language codes |
| `plugins` | `enabled` | string | `"languages"` | Comma-separated plugin names |

All other sections are custom and plugin-specific.

## Debugging Configuration

To see the active configuration, create a debug page:

**content/debug.php:**

```php
<?php
global $config;
echo '<pre>';
print_r($config);
echo '</pre>';
?>
```

Visit `/debug/` to see the merged configuration array.

**Remember to delete this page** before deploying to production.

## What's Next?

- **[Metadata Reference](#)** — Configure individual pages with `metadata.ini`
- **[Template Variables](#)** — Access configuration in templates
- **[Creating Plugins](#)** — Use configuration in custom plugins