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:

[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).

[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:

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

[plugins]

Controls which plugins are loaded.

[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:

[plugins]
enabled = "languages"

To disable all plugins, leave the value empty:

[plugins]
enabled = ""

Custom Sections

Add your own configuration sections for custom plugins:

[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:

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:

[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:

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

[plugins]
enabled = "languages"

Good:

# Only change the default language
[languages]
default = "no"

2. Use Comments

[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:

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

4. Organize by Purpose

# 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

# 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:

[languages]
default = "en"

custom/config.prod.ini:

[api]
key = "production-key"

Load production config in your deployment script:

cat custom/config.prod.ini >> custom/config.ini

Option 3: Environment variables

Read from environment variables in a custom plugin:

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:

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:

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
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