 |
VOOZH | about |
|
VOOZH | about |
This document describes migration strategies and patterns for upgrading StaticForge installations between versions, handling breaking changes, and maintaining backward compatibility. It covers template migrations, configuration updates, PHP version upgrades, and feature compatibility patterns.
For information about testing new versions, see Testing Strategy. For guidance on extending core functionality, see Extending the Core.
StaticForge follows semantic versioning with a multi-layered upgrade approach that prioritizes non-destructive updates and backward compatibility.
Migration Workflow:
composer show eicc/staticforgecomposer.json version constraint and run composer updateaudit:config to identify missing or deprecated configuration.env and siteconfig.yamlSources:
The template migration system ensures new templates are installed without destroying user customizations.
Diagram: Template Migration Flow
Non-Destructive Installation Pattern:
The template installer implements a copy-if-not-exists pattern that protects user customizations:
This ensures that:
Context Detection:
The script detects whether it's running in a library installation or project root:
| Context | Detection Logic | Action |
|---|---|---|
| Library Install | basename(dirname(__DIR__)) === 'staticforge' && basename($vendorDir) === 'vendor' | Copy templates from vendor to project |
| Project Root | Otherwise | Skip (templates already in place) |
| Source Path | __DIR__ . '/../templates' | Library templates directory |
| Target Path | dirname($vendorDir) . '/templates' | Project templates directory |
Sources:
Configuration migration handles the evolution of environment variables and site configuration structure across versions.
Diagram: Configuration Migration Pattern
Default Fallback Pattern:
The bootstrap implements defensive defaults that ensure backward compatibility:
Migration Strategy:
| Configuration Change | Migration Pattern | Example |
|---|---|---|
| New Required Variable | Add to .env.example, add default in bootstrap | LOG_LEVEL defaulting to INFO |
| New Optional Variable | Add to .env.example only, check before use | GOOGLE_ANALYTICS_ID |
| Renamed Variable | Support both names with deprecation warning | Read old name, write to new name |
| Moved to siteconfig.yaml | Read from both sources with priority | TEMPLATE from siteconfig > .env |
| Removed Variable | Continue reading but don't use, log warning | Deprecated feature toggles |
Sources:
Path normalization ensures compatibility across different installation contexts and operating systems.
Diagram: Path Normalization Flow
Normalization Implementation:
The path normalization function handles multiple path formats to support migrations across different environments:
Supported Path Formats:
| Format | Example | Detection | Action |
|---|---|---|---|
| Unix Absolute | /var/www/content | Starts with / | Return unchanged |
| Windows Absolute | C:\Projects\content | Matches [A-Z]:\ | Return unchanged |
| Stream Wrapper | vfs://test/content | Contains :// | Return unchanged |
| Relative Path | content | None of above | Prepend $appRoot |
App Root Discovery:
The bootstrap discovers the application root by traversing up the directory tree:
Sources:
The Container class provides both setVariable and updateVariable methods to support configuration migrations.
Diagram: Container Variable Migration
Migration Pattern Examples:
| Scenario | Method | Use Case |
|---|---|---|
| Initial Bootstrap | setVariable() | Setting configuration from .env during bootstrap |
| CLI Override | updateVariable() | Command-line --input or --output options overriding defaults |
| Feature Configuration | setVariable() | Feature registering its own variables (fails if conflict) |
| Test Setup | updateVariable() | Tests overriding configuration for isolated testing |
| Template Override | updateVariable() | Command-line --template option overriding siteconfig |
Usage in Tests:
Tests demonstrate the migration-safe pattern for configuration updates:
Usage in Commands:
The RenderSiteCommand shows runtime configuration override:
Sources:
Features must maintain backward compatibility across versions while supporting new functionality.
Diagram: Feature Override Pattern
Priority-Based Override System:
The feature discovery system implements a cascade override pattern:
User Features (Highest Priority)
src/Features/MarkdownRenderer with additional processingComposer Features (Medium Priority)
composer.json"extra": {"staticforge": {"feature": "Vendor\\Feature"}}Library Features (Lowest Priority)
vendor/eicc/staticforge/src/Features/Migration Strategy for Feature Updates:
| Update Type | Strategy | Example |
|---|---|---|
| Core Feature Enhancement | Update library, user overrides preserved | Library updates MarkdownRenderer, user version kept if exists |
| New Optional Feature | Add to library, auto-discovered | New ImageOptimizer feature added in v1.20 |
| Breaking Feature Change | Version bump, migration guide provided | RssFeed signature changes in v2.0 |
| Feature Deprecation | Mark deprecated, continue working, remove in next major | OldFeature deprecated in v1.18, removed in v2.0 |
Backward Compatible Feature Pattern:
Features should implement defensive coding for configuration:
Sources:
StaticForge version 1.19.2 requires PHP 8.4+, which represents a major breaking change for existing installations.
Diagram: PHP Version Upgrade Path
PHP 8.4 Breaking Changes Impact:
| PHP Feature | Impact | Migration Action |
|---|---|---|
| Type Declarations | Stricter type checking | Review all type hints, ensure compatibility |
| Deprecated Functions | Removed deprecated features | Update code using deprecated functions |
| Error Handling | More errors elevated to exceptions | Add try-catch blocks as needed |
| Array Functions | Modified behavior | Test array manipulation code |
| String Functions | Changed string handling | Verify string processing |
Composer Constraint Update:
Docker Migration Example:
For containerized deployments, update the PHP version in Dockerfile or docker-compose.yml:
Sources:
The CacheBuster feature demonstrates version-independent state management.
Diagram: Build ID Generation Flow
Migration-Safe Implementation:
The CacheBuster feature sets variables early in the lifecycle:
Version Compatibility:
| Version | Build ID Format | Container Variable | Template Variable |
|---|---|---|---|
| 1.x | Unix timestamp | build_id, cache_buster | {{ cache_buster }} |
| 2.x (future) | Git commit hash | build_id, cache_buster | {{ cache_buster }} |
The abstraction through container variables ensures templates and features continue working regardless of the build ID generation strategy.
Sources:
The test suite demonstrates patterns for ensuring backward compatibility during migrations.
Diagram: Test Configuration Override
Test Isolation Pattern:
Integration tests demonstrate the migration-safe pattern for configuration:
Migration Testing Checklist:
Sources:
The audit:config command helps identify migration issues.
Diagram: Configuration Audit Flow
Configuration Interface:
Features declare their configuration requirements:
Migration Use Case:
After upgrading StaticForge versions:
Sources:
Backup Current Installation
Check Current Version
Review Changelog
CHANGELOG.md for breaking changesUpdate Dependencies
Migrate Templates
Update Configuration
Audit Configuration
Test Build
Review Output
Commit Changes
Sources:
Refresh this wiki