Configuration System

Purpose and Scope

This document provides an overview of StaticForge's multi-tier configuration architecture, including how configuration sources are loaded, resolved, and accessed by components. The configuration system manages environment-specific settings, site metadata, feature settings, and runtime parameters.

For detailed information about specific configuration files and their options, see:

• Environment Variables (.env) - Infrastructure and deployment settings
• Site Configuration (siteconfig.yaml) - Site metadata and feature configuration
• Configuration Resolution - Priority rules and normalization logic

For information about content metadata (frontmatter), see Content Files & Frontmatter.

---

Configuration Architecture

StaticForge implements a four-tier configuration system where each source can override values from lower-priority sources. Configuration is loaded once during bootstrap and stored in two locations: the Container service registry and the $_ENV superglobal.

Configuration Tier Priority

Sources: src/bootstrap.php60-186

Configuration Storage Locations

Storage	Purpose	Access Pattern	Populated By
$_ENV	Raw environment variables	Direct array access: $_ENV['KEY']	Dotenv library
Container	Processed configuration	$container->getVariable('key')	Bootstrap script
site_config	Parsed YAML structure	$container->getVariable('site_config')	Yaml::parseFile

Sources: src/bootstrap.php128-171

---

Configuration Loading Process

The bootstrap sequence loads configuration sources in priority order, with each source potentially overriding previous values.

Bootstrap Configuration Flow

Sources: src/bootstrap.php1-257 composer.json26

---

Path Normalization

All directory paths are normalized to absolute paths during bootstrap to ensure consistent file operations regardless of the working directory.

Path Normalization Logic

The normalizePath closure handles multiple path formats:

Implementation:

Sources: src/bootstrap.php95-109

---

Configuration Sources

1. Hardcoded Defaults

Provides sensible defaults for standard PHP project layouts when no configuration is provided.

Variable	Default Value	Purpose
SOURCE_DIR	content	Content file directory
OUTPUT_DIR	public	Generated HTML output
TEMPLATE_DIR	templates	Twig template location
LOG_DIR	logs	Log file storage
LOG_LEVEL	INFO	Logging verbosity
TEMPLATE	staticforce	Active template name

Sources: src/bootstrap.php111-126

2. Environment Variables (.env)

Stores environment-specific and sensitive configuration that should not be committed to version control.

Key Categories:

• Infrastructure: SITE_BASE_URL, UPLOAD_URL
• Directories: SOURCE_DIR, OUTPUT_DIR, TEMPLATE_DIR
• Deployment: SFTP_HOST, SFTP_USERNAME, SFTP_PASSWORD, SFTP_REMOTE_PATH
• Cloud Services: S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY
• Observability: LOG_LEVEL, LOG_FILE

Sources: .env.example1-42 src/bootstrap.php60-77

3. Site Configuration (siteconfig.yaml)

Contains version-controlled site metadata and feature settings that are consistent across environments.

Key Sections:

• site: Site name, tagline, template selection
• menu: Static menu definitions (top, footer, utility)
• chapter_nav: Sequential navigation configuration
• forms: Form definitions and validation rules
• search: Search engine configuration
• calendars: Calendar view settings
• disabled_features: Feature toggle list
• Feature-specific sections (e.g., google_analytics)

Sources: siteconfig.yaml1-84 src/bootstrap.php143-171

4. CLI Options

Runtime overrides provided via command-line flags. These take precedence over all other sources.

Common Options:

• --template: Override active template
• --input: Override SOURCE_DIR
• --output: Override OUTPUT_DIR

Sources: bin/staticforge.php

---

Template Resolution

Template selection follows a cascading resolution pattern with three potential sources.

Template Resolution Flow

Priority Order:

1. siteconfig.yaml → site.template (highest)
2. .env → TEMPLATE
3. Hardcoded default → 'staticforce' (lowest)

Sources: src/bootstrap.php173-186

---

Service Registration

The bootstrap process registers core services as singleton instances in the Container for dependency injection.

Core Service Registration

Service	Class	Registration Method	Dependencies
logger	EICC\Utils\Log	Container::stuff	LOG_FILE, LOG_LEVEL
twig	Twig\Environment	Container::stuff	TEMPLATE_DIR, TEMPLATE
EventManager	EICC\StaticForge\Core\EventManager	Container::add	Container
AssetManager	EICC\StaticForge\Core\AssetManager	Container::add	None
FeatureManager	EICC\StaticForge\Core\FeatureManager	Container::add	Container, EventManager
ExtensionRegistry	EICC\StaticForge\Core\ExtensionRegistry	Container::add	Container
FileDiscovery	EICC\StaticForge\Core\FileDiscovery	Container::add	Container, ExtensionRegistry
FileProcessor	EICC\StaticForge\Core\FileProcessor	Container::add	Container, EventManager
ErrorHandler	EICC\StaticForge\Core\ErrorHandler	Container::add	Container

Registration Pattern:

Sources: src/bootstrap.php189-254

---

Configuration Access Patterns

Components access configuration through the Container instance passed via constructor injection.

Feature Configuration Access

Usage Example:

Sources: content/development/features.md96-123

Container Variable Access

Sources: src/bootstrap.php128-171

---

Feature Configuration Integration

Features can declare configuration requirements and access their settings through a standardized interface.

ConfigurableFeatureInterface Pattern

Features implementing ConfigurableFeatureInterface provide self-documentation of their configuration needs:

Benefits:

• audit:config command validates complete setup
• Self-documenting configuration requirements
• Runtime validation with meaningful error messages

Sources: bin/staticforge.php Diagram 1 analysis

---

Menu System Configuration

StaticForge supports two independent menu systems that coexist without conflict.

Menu Configuration Architecture

Menu Type	Source	Access Pattern	Example Keys
Named Menus	siteconfig.yaml → menu:	{{ menu_top }}, {{ menu_footer }}	top, footer, utility
Numbered Menus	Content frontmatter → menu: X.Y	{{ menu1 }}, {{ menu2 }}	1, 2, 3, 4

Configuration Example:

Sources: siteconfig.yaml16-22 siteconfig.yaml.example24-37 Diagram 4 analysis

---

Error Handling

The bootstrap process implements graceful degradation for configuration errors.

Configuration Error Behavior

Error Type	Behavior	Impact
Missing .env	Continue with defaults	Logs warning, uses hardcoded defaults
Invalid siteconfig.yaml syntax	Throw RuntimeException	Fatal error, halts bootstrap
Missing required env var	Runtime validation	Error at point of use
Invalid path format	Normalized to relative	Prepends app_root

YAML Parse Error Example:

Sources: src/bootstrap.php153-165

---

Configuration Best Practices

Separation of Concerns

Configuration Type	Storage Location	Version Control
Secrets & Credentials	.env	❌ Never commit (.gitignore)
Environment URLs	.env	❌ Environment-specific
Site Metadata	siteconfig.yaml	✅ Commit to repository
Feature Settings	siteconfig.yaml	✅ Shared across environments
Infrastructure Paths	.env	❌ May differ per environment

Configuration Validation

1. Required Variables: Check existence before use with null coalescing: $_ENV['KEY'] ?? 'default'
2. Type Safety: Cast values from environment: (bool)$_ENV['FLAG'], (int)$_ENV['PORT']
3. Path Validation: Verify directories exist before operations
4. Graceful Defaults: Provide sensible fallbacks for optional settings

Sources: src/bootstrap.php111-126 content/guide/configuration.md15-56

---

Summary

The configuration system provides:

1. Four-tier resolution with predictable override semantics
2. Path normalization for cross-platform compatibility
3. Dual storage in Container and $_ENV for different access patterns
4. Template resolution with cascading fallbacks
5. Service registration for dependency injection
6. Feature configuration through standardized interfaces
7. Dual menu systems for static and dynamic navigation
8. Error handling with graceful degradation

All configuration loading occurs once during bootstrap (src/bootstrap.php1-257), producing a fully configured Container instance that is passed to all components.

Sources: src/bootstrap.php1-257 siteconfig.yaml1-84 .env.example1-42 Diagram 4 analysis