Configuration Resolution

Purpose and Scope

This document explains how StaticForge resolves configuration values from multiple sources (hardcoded defaults, .env files, siteconfig.yaml, and CLI options) into a single unified configuration system. It covers the priority hierarchy, path normalization logic, and the bootstrap process that assembles configuration during application startup.

For documentation on individual configuration options, see Environment Variables (.env) and Site Configuration (siteconfig.yaml). For information on how the Container manages these values at runtime, see Dependency Injection Container.

---

Configuration Source Hierarchy

StaticForge resolves configuration values from four sources, with each source having the ability to override values from lower-priority sources.

Configuration Source Priority Diagram

Sources: src/bootstrap.php61-186

Priority Rules

Priority	Source	Purpose	Example Values
1 (Lowest)	Hardcoded Defaults	Sensible fallbacks for standard PHP project structure	SOURCE_DIR='content', OUTPUT_DIR='public', TEMPLATE='staticforce'
2	.env File	Environment-specific infrastructure configuration	SITE_BASE_URL, SFTP_HOST, LOG_LEVEL
3	siteconfig.yaml	Site-specific, version-controlled configuration	site.name, menu definitions, feature settings
4 (Highest)	CLI Options	Runtime overrides for development workflows	--template, --input, --output

Sources: src/bootstrap.php111-186 content/guide/configuration.md33-56

---

Configuration Loading Process

Bootstrap Sequence

Sources: src/bootstrap.php1-257 content/development/bootstrap.md17-73

Application Root Detection

The bootstrap determines the project root by traversing up the directory tree from the current working directory:

Sources: src/bootstrap.php79-93

---

Path Normalization

All directory paths are normalized to absolute paths during bootstrap to ensure consistent behavior regardless of the working directory when bin/staticforge.php is invoked.

Path Normalization Logic

Implementation:

Sources: src/bootstrap.php95-109

Path Normalization Examples

Input Path	Context	Normalized Output
content	appRoot = /var/www/site/	/var/www/site/content
/var/www/site/content	Any appRoot	/var/www/site/content (already absolute)
C:\Projects\site\content	Windows	C:\Projects\site\content (already absolute)
vfs://test/content	Testing with vfsStream	vfs://test/content (stream wrapper)

Sources: src/bootstrap.php95-124

---

Template Resolution

Template selection demonstrates the cascade override pattern, with special logic to prefer siteconfig.yaml over .env for this specific value.

Template Resolution Decision Tree

Implementation:

Sources: src/bootstrap.php173-186 content/guide/configuration.md150-165

Why This Order?

The template resolution logic implements a specific philosophy:

1. siteconfig.yaml is preferred because it's version-controlled and site-specific. Multiple developers working on the same project should use the same template by default.

2. .env provides override capability for local development without modifying version-controlled files (e.g., testing a new template locally).

3. 'staticforce' is the fallback ensuring the system works out-of-box without any configuration.

Sources: src/bootstrap.php173-186 siteconfig.yaml.example13-16

---

Runtime Configuration Access

Once bootstrap completes, configuration values are stored in two locations depending on their nature:

Configuration Storage Locations

Sources: src/bootstrap.php128-171

Container Variable Access

Most components access configuration through the Container:

Sources: src/Core/FileDiscovery.php40-54 src/Features/MenuBuilder/Feature.php50-68

Environment Variable Direct Access

Some components may also read directly from $_ENV:

Sources: src/bootstrap.php191-205

---

Variable Initialization Order

Understanding when each configuration value becomes available is critical for feature development:

Phase	Variables Available	Notes
1. Dotenv Load	$_ENV populated from .env	Lines 61-77
2. Defaults Applied	SOURCE_DIR, OUTPUT_DIR, TEMPLATE_DIR, LOG_DIR, LOG_FILE, LOG_LEVEL, TEMPLATE	Lines 111-126
3. Paths Normalized	All directory paths are absolute	Lines 113-123
4. Container Created	app_root variable set	Lines 129-130
5. Env Vars Copied	All $_ENV variables copied to Container (except TEMPLATE)	Lines 132-141
6. SiteConfig Loaded	site_config array available in Container	Lines 143-171
7. Template Resolved	Final TEMPLATE value stored in Container	Lines 173-186
8. Services Registered	logger, twig, core services available	Lines 190-255

Sources: src/bootstrap.php1-257

---

Special Configuration Cases

Menu Resolution

StaticForge supports two independent menu systems that are resolved differently:

Static Menus (from siteconfig.yaml):

• Stored in Container::site_config['menu']
• Processed by MenuBuilder at priority 100 during POST_GLOB
• Output as menu_top, menu_footer, etc.

Dynamic Menus (from content frontmatter):

• Built from files with menu: X.Y metadata
• Processed by MenuBuilder at priority 100 during POST_GLOB
• Output as menu1, menu2, etc.

Sources: siteconfig.yaml16-22 src/Features/MenuBuilder/Feature.php50-120

Feature Configuration

Features access their configuration from the site_config array:

Features can also check for feature toggles:

Sources: siteconfig.yaml69-70 src/Core/FeatureManager.php45-89

Chapter Navigation Configuration

The ChapterNav feature demonstrates fallback configuration logic:

1. First, check siteconfig.yaml['chapter_nav']
2. If not found, check $_ENV['CHAPTER_NAV_MENUS'] and related variables
3. Use defaults if neither source provides values

Sources: siteconfig.yaml24-28 content/guide/site-config.md194-223

---

Configuration Priority Examples

Example: SOURCE_DIR Resolution

Concrete Example:

Configuration	Value	Result
Default	'content'	/var/www/site/content
.env: SOURCE_DIR="posts"	'posts'	/var/www/site/posts
CLI: --input=/data/files	/data/files	/data/files (absolute, unchanged)

Sources: src/bootstrap.php111-126 bin/staticforge.php70-85

Example: SITE_BASE_URL Resolution

Configuration	Value	Notes
Default	(none)	No hardcoded default
.env: SITE_BASE_URL="http://localhost:8000/"	"http://localhost:8000/"	Required for operation
CLI Override	Not supported	SITE_BASE_URL cannot be overridden via CLI

Note: SITE_BASE_URL must be defined in .env or as an environment variable. The application will fail if this value is missing when features attempt to generate URLs.

Sources: .env.example4 content/guide/configuration.md66-90

---

Configuration Validation

StaticForge performs minimal validation during bootstrap. Most validation occurs lazily when features access configuration values:

Bootstrap-Time Validation

• File Format Validation: siteconfig.yaml must be valid YAML syntax or bootstrap throws RuntimeException (lines 154-165)
• Path Existence: No validation that directories exist during bootstrap; directories are created on-demand by components

Runtime Validation

Individual features and commands validate their required configuration:

Sources: src/bootstrap.php154-165 src/Core/FileDiscovery.php40-54

---

Configuration Override Workflow

The most common workflow for overriding configuration:

Best Practices:

1. Never commit .env — Use .env.example as a template
2. Always commit siteconfig.yaml — This is version-controlled site configuration
3. Use CLI options sparingly — Mainly for testing, not production builds
4. Document custom paths — If you change SOURCE_DIR or OUTPUT_DIR, document why

Sources: content/guide/configuration.md444-467 README.md37-47

---

Troubleshooting Configuration Resolution

Common Issues

Symptom	Likely Cause	Solution
"SOURCE_DIR does not exist"	Relative path resolved incorrectly	Check working directory, ensure .env or composer.json exists at project root
Template not found	TEMPLATE variable incorrect	Check siteconfig.yaml['site']['template'] and .env['TEMPLATE']
Assets broken in output	SITE_BASE_URL missing trailing slash	Add trailing slash to SITE_BASE_URL in .env
Configuration ignored	.env in wrong directory	Bootstrap searches getcwd(), not script directory
YAML parse error	Invalid siteconfig.yaml syntax	Use YAML validator, check for tabs vs spaces

Sources: src/bootstrap.php154-165 content/guide/configuration.md375-395

Debugging Configuration

To debug configuration resolution:

1. Check loaded values:

2. Verify application root:

3. Check siteconfig loading:

4. Enable debug logging:

Sources: content/development/bootstrap.md232-242 content/guide/configuration.md198-211