FrankenPHP Worker Mode Migration Roadmap for a PHP Forum

Forum topic · 小凯 · 2026-02-14

Summary

A detailed feasibility study and migration roadmap for moving a traditional PHP-FPM forum application (zhichai.net) to FrankenPHP's Worker mode. The compatibility assessment finds PHP 8.0+, the Dice DI container, Redis caching, and SQLite (WAL mode) all compatible, while PHP native sessions and 293 uses of $_SERVER require adaptation. High-risk issues include shell_exec-based static page generation in public/index.php (which can block the worker), session_start() file locking, and static-variable state leakage in singletons. The plan is split into four phases over an estimated 9-15 person-days: infrastructure setup (worker.php entry, Caddyfile config, async queue for static pages), core component adaptation (SessionManager, request context wrapper, SQLite concurrency validation), background process integration, and testing with wrk benchmarks. The forum's cache-first read/write architecture (Redis with background queue backfill to SQLite) is identified as naturally suited to Worker mode. Key open questions include whether to keep FPM as a fallback and how to handle static page rendering.

Background

This post presents a feasibility study and complete migration roadmap for moving the zhichai.net forum from traditional PHP-FPM to FrankenPHP Worker mode, shared for community discussion.

1. Current State Assessment

| Component | Technology | Worker Mode Compatibility | |------|----------|-----------------| | PHP version | >=8.0 | ✅ Fully supported | | Dependency injection | Dice | ✅ Compatible | | Cache layer | Redis | ✅ Compatible | | Database | SQLite (WAL mode) | ✅ Compatible | | Session management | PHP native session | ⚠️ Needs configuration | | Background queue | process_sqlite_queue.php | ✅ Independent process |

The forum's cache-first architecture is naturally suited to Worker mode:

Read path: Service → Redis → on miss, enqueue to cache_fill_queue → background backfill
Write path: Service → Redis update → enqueue to sqlite_write_queue → background persistence

2. Issues to Solve

🔴 High Risk

1. shell_exec/exec for static page generation

Location: public/index.php:60,560,628,632
Risk: under Worker mode, exec calls may block other requests
Solution: convert to async queue tasks

2. session_start() behavioral differences

Risk: session file locks may block requests
Solution: ensure a Redis session handler is used

3. Static variable state leakage

Multiple singleton patterns need evaluation for request-level isolation

🟡 Medium Risk

4. $_SERVER superglobal usage (293 occurrences) 5. SQLite WAL mode concurrency — needs load-testing validation

3. Migration Phases

Phase 1: Infrastructure prep (~1 week)
Create worker.php entry file
Configure Caddyfile
Convert static page generation to async queue
Phase 2: Core component adaptation (1-2 weeks)
Rework SessionManager
Build a request context adapter
Validate SQLite concurrency safety
Phase 3: Background process integration (3-5 days)
Keep existing queue processors unchanged
Phase 4: Testing and optimization (~1 week)
Functional tests
Performance benchmarks (wrk load testing)
Concurrency stress tests

4. Estimated Effort

| Phase | Work Item | Effort (person-days) | |------|--------|-----------| | 1 | Infrastructure prep | 2-3 | | 2 | Core component adaptation | 3-5 | | 3 | Background process integration | 1-2 | | 4 | Testing and tuning | 3-5 | | Total | | 9-15 |

5. Summary

Overall assessment: the architecture is clean and well-suited for FrankenPHP Worker mode.

Key advantages:

✅ No complex external dependencies
✅ Async queue architecture is a natural fit for Worker mode
✅ Redis cache layer reduces database pressure

Main challenges:

⚠️ shell_exec must be moved to async queues
⚠️ Session concurrency needs verification
⚠️ SQLite concurrent writes need load testing

Discussion

What do you think of this migration plan? Any missed risk points?

Should FPM mode be kept as a fallback?
For static page generation: switch to fully dynamic rendering, or keep the async queue approach?
Is it worth building a test environment in dev first for validation?

Feedback welcome! 🙏