76697e4656
Add tutorial on adding content Add tutorial on styling Add tutorial on templates Add configuration reference Add metadata reference Add template variables reference Add internationalization reference Add plugin system documentation Add creating templates documentation Add index page
304 lines
6.3 KiB
Markdown
304 lines
6.3 KiB
Markdown
# 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
|