 |
VOOZH | about |
|
VOOZH | about |
This document describes the bootstrap process in StaticForge, which initializes the application environment before any commands execute. The bootstrap is responsible for autoloader discovery, environment configuration, container setup, and core service registration.
For information about the dependency injection container itself, see Dependency Injection Container. For details on how features are discovered and loaded after bootstrap, see Feature Architecture. For CLI command initialization, see Site Commands.
The bootstrap process is implemented as a procedural script at src/bootstrap.php1-258 that executes in a defined sequence and returns a fully configured Container instance.
Sources: src/bootstrap.php1-258 bin/staticforge.php1-60
The bootstrap checks if Composer's autoloader is already loaded before attempting to load it, preventing duplicate autoloader registration.
The system searches for autoload.php in the following locations:
| Priority | Path | Use Case |
|---|---|---|
| 1 | __DIR__ . '/../vendor/autoload.php' | Development install (git clone) |
| 2 | __DIR__ . '/../../../autoload.php' | Library install (composer require) |
| 3 | getcwd() . '/vendor/autoload.php' | Fallback to current directory |
The check at src/bootstrap.php25 verifies if Composer\Autoload\ClassLoader exists before attempting autoloader discovery. If no autoloader is found, a RuntimeException is thrown at src/bootstrap.php42
Sources: src/bootstrap.php23-44 composer.json38-46
Environment variables are loaded from .env files using vlucas/phpdotenv and stored in the $_ENV superglobal.
The createUnsafeMutable() method at src/bootstrap.php72 allows overwriting existing environment variables, which is necessary when the script is invoked multiple times in tests.
If environment variables are not set, the bootstrap establishes defaults at src/bootstrap.php113-126:
SOURCE_DIR = "content"
TEMPLATE_DIR = "templates"
OUTPUT_DIR = "public"
LOG_DIR = "logs"
LOG_FILE = "{LOG_DIR}/staticforge.log"
LOG_LEVEL = "INFO"
TEMPLATE = "staticforce"
Sources: src/bootstrap.php60-77 src/bootstrap.php111-127 .env.example1-42
All directory paths are normalized to absolute paths to ensure consistent path resolution regardless of the working directory when the CLI is invoked.
The $normalizePath closure at src/bootstrap.php96-109 implements the following rules:
| Path Pattern | Detection | Action |
|---|---|---|
| Absolute Unix | Starts with / | Return as-is |
| Absolute Windows | Matches /^[a-zA-Z]:\\/ | Return as-is |
| Stream wrapper | Contains :// | Return as-is (e.g., vfs:// for tests) |
| Relative | None of above | Prepend $appRoot |
The $appRoot is determined by traversing upward from getcwd() until finding a directory containing either composer.json or .env (lines src/bootstrap.php80-93):
This allows StaticForge to be invoked from subdirectories while correctly locating project resources.
Sources: src/bootstrap.php80-109 src/bootstrap.php113-123
The Container class from the eicc/utils package is instantiated at src/bootstrap.php129 and serves as the central service registry and configuration store.
The bootstrap populates the container in this order:
app_root as the first variable$_ENV entries except TEMPLATEsiteconfig.yaml as site_configTEMPLATE valueThe TEMPLATE variable uses a three-tier priority system at src/bootstrap.php173-186:
Priority 1: siteconfig.yaml['site']['template']
Priority 2: $_ENV['TEMPLATE']
Priority 3: Default "staticforce"
This allows siteconfig.yaml (version-controlled) to override .env (environment-specific).
Sources: src/bootstrap.php129-187
The siteconfig.yaml file is loaded using Symfony's YAML parser at src/bootstrap.php146-168
| Priority | Path | Context |
|---|---|---|
| 1 | getcwd() . '/siteconfig.yaml' | Current working directory |
| 2 | $appRoot . 'siteconfig.yaml' | Application root directory |
If parsing fails, a RuntimeException is thrown with the parse error message at src/bootstrap.php160-164
The parsed YAML structure (or empty array if file doesn't exist) is stored as the site_config container variable at src/bootstrap.php171 This data structure is accessed by features for configuration values.
For details on the siteconfig.yaml structure and options, see Site Configuration (siteconfig.yaml).
Sources: src/bootstrap.php143-171 siteconfig.yaml1-556
The bootstrap registers all core services as singleton instances in the container. This ensures that all components share the same service instances throughout the application lifecycle.
| Service | Registration Method | Class | Lines |
|---|---|---|---|
logger | stuff() | EICC\Utils\Log | src/bootstrap.php191-205 |
twig | stuff() | Twig\Environment | src/bootstrap.php208-232 |
EventManager | add() | EICC\StaticForge\Core\EventManager | src/bootstrap.php235-236 |
AssetManager | add() | EICC\StaticForge\Core\AssetManager | src/bootstrap.php238-239 |
FeatureManager | add() | EICC\StaticForge\Core\FeatureManager | src/bootstrap.php241-242 |
ExtensionRegistry | add() | EICC\StaticForge\Core\ExtensionRegistry | src/bootstrap.php244-245 |
FileDiscovery | add() | EICC\StaticForge\Core\FileDiscovery | src/bootstrap.php247-248 |
ErrorHandler | add() | EICC\StaticForge\Core\ErrorHandler | src/bootstrap.php250-251 |
FileProcessor | add() | EICC\StaticForge\Core\FileProcessor | src/bootstrap.php253-254 |
The logger service factory at src/bootstrap.php191-205 reads configuration from $_ENV directly:
EICC\Utils\Log with log file path and levelRuntimeException if directory creation failsThe Twig service factory at src/bootstrap.php208-232 performs the following:
TEMPLATE_DIR from containerFilesystemLoader with template directorySources: src/bootstrap.php190-254
The bootstrap is invoked in two primary contexts: CLI execution and test execution.
The CLI entry point at bin/staticforge.php1-60 demonstrates the standard invocation pattern:
The bootstrap must be called exactly once per process. Multiple invocations will cause service registration conflicts.
Test cases use a modified bootstrap process to support virtual filesystems and test-specific configuration.
The UnitTestCase base class at tests/Unit/UnitTestCase.php demonstrates the pattern:
Tests can use virtual filesystem (vfsStream) for most directories, but TEMPLATE_DIR must use real filesystem paths because Twig's loader cannot read from stream wrappers (tests/Unit/Features/HtmlRenderer/FeatureTest.php35-36).
Sources: bin/staticforge.php1-60 tests/Unit/Features/HtmlRenderer/FeatureTest.php25-68
The bootstrap implements a multi-tier configuration resolution system where later sources override earlier ones.
| Variable | Source 1 (Default) | Source 2 (.env) | Source 3 (siteconfig.yaml) | Final Value |
|---|---|---|---|---|
SOURCE_DIR | "content" | "src/pages" | N/A | "src/pages" |
TEMPLATE | "staticforce" | "sample" | "custom" | "custom" |
SITE_BASE_URL | None | "http://localhost" | N/A | "http://localhost" |
LOG_LEVEL | "INFO" | Not set | N/A | "INFO" |
Note that TEMPLATE has special resolution logic at src/bootstrap.php178-184 where siteconfig.yaml['site']['template'] takes precedence over $_ENV['TEMPLATE'].
For complete configuration documentation, see Configuration Resolution.
Sources: src/bootstrap.php111-187 content/development/templates.md173-195
The bootstrap script returns the fully configured Container instance at src/bootstrap.php257 This container contains:
TEMPLATE)app_root pathsite_config from YAMLTEMPLATE valuelogger, twig)The calling code (typically bin/staticforge.php or test setup methods) receives this container and uses it to construct application-level objects like commands and the Symfony Console Application.
Refresh this wiki