 |
VOOZH | about |
|
VOOZH | about |
This page provides a comprehensive guide to building custom features for StaticForge. It covers the architecture, implementation patterns, and best practices for extending the system with your own functionality.
For information about the overall feature architecture and discovery mechanism, see Feature Architecture. For details on using built-in features, see Built-in Features Overview. For distributing features via Composer, see External Features.
The following diagram illustrates the complete lifecycle of creating and registering a custom feature:
Diagram: Feature Development and Registration Lifecycle
Sources:
Features reside in src/Features/ with the following structure:
src/Features/MyFeature/
├── Feature.php # Main feature class (required)
├── Services/ # Service classes (optional)
│ └── MyFeatureService.php
└── Models/ # Data models (optional)
└── MyModel.php
The FeatureManager scans for directories containing a Feature.php file during bootstrap.
Sources:
Diagram: BaseFeature Class Hierarchy
Minimal Feature Example:
Sources:
The eventListeners property is a declarative mapping of events to handler methods. BaseFeature.register() automatically registers these listeners during feature initialization.
Array Structure:
| Key | Value Type | Description |
|---|---|---|
| Event name | ['method' => string, 'priority' => int] | Event → Handler mapping |
Example:
Sources:
Events execute in ascending priority order (lower numbers first):
| Priority Range | Use Case |
|---|---|
| 0-50 | Early initialization, dependency setup |
| 50-100 | Standard processing, data collection |
| 100-200 | Data transformation, enrichment |
| 200-500 | Final processing, cleanup |
| 500+ | Late-stage modifications |
Critical Priority Interactions:
POST_GLOB Event:
├─ CategoryIndex (50) - Creates category index pages
├─ MenuBuilder (100) - Builds menus (needs index pages to exist)
├─ Tags (150) - Processes tags
└─ Categories (250) - Applies category templates
Sources:
All event handlers must follow this signature:
Key Rules:
Container and array parametersarray (always)Sources:
The Container provides access to all registered services and configuration:
Diagram: Container Service Access Patterns
Common Container Methods:
| Method | Purpose | Example |
|---|---|---|
get(string) | Retrieve service instance | $container->get('logger') |
getVariable(string) | Retrieve configuration value | $container->getVariable('OUTPUT_DIR') |
setVariable(string, mixed) | Store data for other features | $container->setVariable('my_data', $value) |
add(string, object) | Register service (rarely needed in features) | $container->add('my_service', $instance) |
Sources:
Every feature has access to a shared logger instance:
Log Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
Sources:
Extract business logic into service classes when:
Example Service Structure:
src/Features/MyFeature/
├── Feature.php # Thin orchestration layer
└── Services/
├── MyFeatureService.php # Core business logic
└── DataTransformService.php # Specialized transformations
Feature.php (Orchestrator):
Services/MyFeatureService.php (Business Logic):
Sources:
Features requiring configuration should implement ConfigurableFeatureInterface:
This enables validation via audit:config command.
Sources:
From siteconfig.yaml:
From Environment Variables:
Configuration Hierarchy:
siteconfig.yaml → BaseFeature.getConfig() → Returns site_config[feature_name]
.env → $_ENV or getenv()
Container Variables → container.getVariable()
Sources:
Features expose data to templates by storing it in the features parameter:
Template Access:
Sources:
Features can fire their own events for extensibility:
Example from RssFeed Feature:
The RssFeed feature fires RSS_BUILDER_INIT and RSS_ITEM_BUILDING events, allowing other features (like Podcast) to extend RSS functionality without modifying the core RSS feature.
Sources:
Access discovered files during POST_GLOB:
discovered_files Structure:
Sources:
Features are loaded in three tiers:
Diagram: Feature Discovery Priority Hierarchy
Features with identical names are resolved by priority: User > Composer > Library.
Sources:
Disable features via siteconfig.yaml:
Disabled features:
Sources:
Create unit tests extending UnitTestCase:
Sources:
To distribute a feature as a Composer package:
my-vendor/my-feature/
├── composer.json
└── src/
└── Features/
└── MyFeature/
├── Feature.php
└── Services/
└── MyService.php
The extra.staticforge.feature key registers the feature class for automatic discovery.
Sources:
This example demonstrates a complete feature that calculates reading time for content:
src/Features/ReadingTime/Feature.php:
Template usage:
Sources:
Custom features in StaticForge follow these principles:
BaseFeature for automatic event registration and container accesseventListeners array for declarative event bindingConfigurableFeatureInterface for features requiring configurationsrc/Features/ for automatic discoveryUnitTestCaseFeatures have full access to the container, discovered files, configuration, and can fire their own events for extensibility.
Sources:
Refresh this wiki