 |
VOOZH | about |
|
VOOZH | about |
This document describes StaticForge's foundational architecture: the bootstrap process, core service registration, dependency injection container, event management system, and file processing pipeline. These components form the infrastructure layer upon which all features and functionality are built.
For configuration management details, see Configuration System. For content processing specifics, see Content Management. For template rendering, see Template System. For the feature plugin architecture, see Feature System.
StaticForge implements a three-layer architecture with dependency injection, event-driven processing, and a modular feature system.
Diagram: Core System Components
Sources: src/bootstrap.php1-258 composer.json38-42
The bootstrap process initializes the application by loading dependencies, parsing configuration, and registering core services. This occurs exactly once per CLI invocation.
Diagram: Bootstrap Sequence
Sources: src/bootstrap.php1-258 src/bootstrap.php23-44 src/bootstrap.php60-77 src/bootstrap.php79-109
Bootstrap attempts to load the Composer autoloader from multiple locations to support both library installation and development contexts:
| Path | Context |
|---|---|
__DIR__ . '/../vendor/autoload.php' | Development (project root) |
__DIR__ . '/../../../autoload.php' | Library installation (vendor/eicc/staticforge/) |
getcwd() . '/vendor/autoload.php' | Working directory fallback |
Sources: src/bootstrap.php26-39
The .env file is loaded using Dotenv::createUnsafeMutable() which populates $_ENV superglobal. Variables are then copied to the Container for backward compatibility. The system sets sensible defaults before loading:
SOURCE_DIR = content
TEMPLATE_DIR = templates
OUTPUT_DIR = public
LOG_DIR = logs
LOG_LEVEL = INFO
TEMPLATE = staticforce
Sources: src/bootstrap.php60-127 .env.example1-42
All directory paths are normalized to absolute paths using the $normalizePath closure. This handles:
$appRoot/[a-zA-Z]:\\:// (e.g., vfs:// for testing)Sources: src/bootstrap.php95-109
The optional siteconfig.yaml file is loaded via Symfony's YAML parser and stored in the Container as site_config. If parsing fails, a RuntimeException is thrown with the parse error details.
Sources: src/bootstrap.php143-168
The Container class (from eicc/utils) provides service registration and variable storage. It supports two registration methods:
| Method | Behavior | Use Case |
|---|---|---|
stuff($key, $value) | Singleton: resolves once, caches result | Stateful services (Logger, Twig) |
add($key, $value) | Direct storage: returns exact value | Pre-instantiated objects |
Diagram: Container Service Registration
Sources: src/bootstrap.php191-205 src/bootstrap.php208-232 src/bootstrap.php235-254
Variables are stored using setVariable($key, $value) and retrieved using getVariable($key). The Container maintains a separate variable namespace from services. Variables can be updated using updateVariable($key, $value).
Sources: src/bootstrap.php130-141 src/bootstrap.php171
StaticForge registers seven core services during bootstrap, each providing specific functionality to the system.
Class: EICC\StaticForge\Core\EventManager
The EventManager implements a priority-based event bus using the on() and fire() methods.
Key Methods:
on(string $event, callable $callback, int $priority = 500): Register event listenerfire(string $event, array $data = []): Dispatch event to registered listenersEvent listeners receive (Container $container, array $data) and must return array $data.
Sources: src/bootstrap.php235-236
Class: EICC\StaticForge\Core\FeatureManager
The FeatureManager discovers and loads features from three locations with priority-based override:
| Priority | Location | Use Case |
|---|---|---|
| HIGHEST | src/Features/ | User features (override library) |
| MEDIUM | Composer packages with extra.staticforge.feature | Third-party features |
| LOWEST | vendor/eicc/staticforge/src/Features/ | Library features |
Features are instantiated and their register() method is called with EventManager and Container.
Sources: src/bootstrap.php241-242
Class: EICC\StaticForge\Core\ExtensionRegistry
The ExtensionRegistry maintains a map of file extensions to handler features. Renderer features register extensions via:
$extensionRegistry->register('.md', 'MarkdownRenderer')
$extensionRegistry->register('.html', 'HtmlRenderer')
The canProcess($extension) method determines if a file type can be handled.
Sources: src/bootstrap.php244-245
Class: EICC\StaticForge\Core\AssetManager
The AssetManager collects CSS and JavaScript assets from features for injection into templates. Features register assets via:
registerStyle($url, $position = 'head')registerScript($url, $position = 'footer')registerInlineScript($code, $position = 'footer')Sources: src/bootstrap.php238-239
Class: EICC\StaticForge\Core\FileDiscovery
FileDiscovery scans content directories, parses frontmatter, and generates URLs. The discoverFiles() method returns an array of file metadata stored in Container as discovered_files.
Sources: src/bootstrap.php247-248
Class: EICC\StaticForge\Core\FileProcessor
FileProcessor orchestrates the build pipeline by firing events at key stages. The processFiles() method iterates discovered files and triggers the rendering loop events.
Sources: src/bootstrap.php253-254
Class: EICC\StaticForge\Core\ErrorHandler
ErrorHandler provides centralized error reporting and logging. It is registered but not invoked during normal bootstrap.
Sources: src/bootstrap.php250-251
The build process follows a deterministic event sequence with priority-based listener execution.
Diagram: Event Firing Sequence
Sources: content/development/events.md31-61 content/development/architecture.md71-102
| Event | Typical Priority | Common Listeners |
|---|---|---|
| CREATE | 500 | Feature initialization |
| PRE_GLOB | 500 | Pre-discovery setup |
| POST_GLOB | 50-250 | CategoryIndex (50), MenuBuilder (100), Categories (250) |
| PRE_RENDER | 500 | Metadata enrichment |
| RENDER | 500 | MarkdownRenderer, HtmlRenderer |
| POST_RENDER | 500 | Asset injection, analytics |
| POST_LOOP | 90-100 | RSSFeed (90), Sitemap, TemplateAssets (100) |
| DESTROY | 500 | Cleanup |
Sources: content/development/architecture.md103-116
FileDiscovery scans directories, parses frontmatter, filters files, and generates URLs before any rendering occurs.
Diagram: FileDiscovery Pipeline
Sources: content/guide/configuration.md346-368 content/development/architecture.md29-62
URLs are constructed through a multi-step transformation:
content/blog/post.md → blog/postblog/post → blog/post.htmlcategory: tech, insert category subdirectory → tech/post.htmlhttps://example.com/tech/post.htmlSources: content/guide/configuration.md346-397
Each entry in discovered_files contains:
This array is stored in Container and becomes the "single source of truth" for the build process.
Sources: content/development/architecture.md38-58
The complete build pipeline integrates all core components through the FileProcessor.
Diagram: Complete Build Pipeline
Sources: content/development/architecture.md68-102 README.md57-64
The Container's state evolves throughout the build:
| Stage | Container Contents |
|---|---|
| Bootstrap | Services, variables, configuration |
| Discovery | + discovered_files array |
| POST_GLOB | + Feature-generated data (menus, tag lists) |
| Rendering Loop | + Per-file rendering context |
| POST_LOOP | + Generated artifact paths |
Sources: src/bootstrap.php129-171
Services registered in the Container follow specific initialization and usage patterns.
Services registered via stuff() use closures that are resolved on first access:
The closure executes once when $container->get('logger') is first called. Subsequent calls return the cached instance.
Sources: src/bootstrap.php191-205
The Twig service uses FilesystemLoader with two paths:
$TEMPLATE_DIR (e.g., templates/)$TEMPLATE_DIR/$TEMPLATE/ (e.g., templates/staticforce/)Configuration options:
debug: truestrict_variables: falseautoescape: 'html'cache: falseSources: src/bootstrap.php208-232
Services registered via add() are pre-instantiated and stored directly:
These services are constructed during bootstrap and passed the Container for dependency access.
Sources: src/bootstrap.php235-254
The system determines which template to use through a three-tier resolution hierarchy:
site.template (highest priority).env fileThis resolution occurs during bootstrap and stores the final value in Container as TEMPLATE.
Sources: src/bootstrap.php173-187
StaticForge's core architecture implements a clean separation between infrastructure (bootstrap, container, events) and application logic (features, processing). The bootstrap process establishes a fully-configured Container with seven core services. The EventManager enables loose coupling between features. FileDiscovery creates a single source of truth for site structure. FileProcessor orchestrates the build through deterministic event firing. This architecture enables extensibility without modifying core code—features simply register event listeners to participate in the build pipeline.
Sources: src/bootstrap.php1-258 composer.json1-60 content/development/architecture.md1-247
Refresh this wiki