Repository navigation
Plugin system → Service Provider model (Wheels 4.0) #1917
Description
Phase 4 — Modernization Target #14 (Wheels 4.0)
Replace the zip-based, mixin-injection plugin system with a Service Provider model.
Current Problems
- Plugins are zip files extracted at boot
- Methods injected via
StructAppendinto variable scopes — collision risk - No namespacing — two plugins with same method name silently overwrite
- No lifecycle hooks for plugins
- Dead code referencing Railo-era workarounds
Proposed Design
component implements="wheels.ServiceProviderInterface" {
function register(container) {
container.map("auth").to("MyAuth.AuthService").asSingleton();
}
function boot(app) {
app.addMiddleware("MyAuth.AuthMiddleware");
app.modelTrait("authenticatable", "MyAuth.Authenticatable");
}
}Migration Path
- In 3.x, introduce
ServiceProviderinterface alongside existing plugin system - Plugins can optionally include
ServiceProvider.cfcfor new-style registration - In 4.0, deprecate mixin injection; require Service Providers
- Ship
wheels-legacy-plugin-adapterfor running old plugins in 4.0
Dependencies
Benefits from expanded DI container (#1912) and middleware pipeline (#1906).
See design_docs/MODERNIZE-WHEELS-RIM.md §4.10 for full implementation plan.
Wheels 4.0 Sub-Issues
- Wheels 4.0: Module system and package format #1966 — Module system and package format
- Wheels 4.0: Interface-driven design contracts Issue #1967 #1967 — Interface-driven design contracts
- Wheels 4.0: Engine adapter modules (Lucee, Adobe, BoxLang) Issue #1968 #1968 — Engine adapter modules (Lucee, Adobe, BoxLang)
- Wheels 4.0: Legacy compatibility adapter and migration path Issue #1969 #1969 — Legacy compatibility adapter and migration path
Activity
bpamiri commentedon Mar 15, 2026
3.x Incremental Modernization Plan
Filed 10 issues to build the foundation for Service Providers incrementally in 3.x, organized in three backward-compatible phases:
Phase 1 — Cleanup & Foundation
plugin.jsonmanifest support alongside box.jsonPhase 2 — DI Integration & Lifecycle
Phase 3 — Migration Path (3.x → 4.0 bridge)
After Phase 3 ships, this issue (#1917) becomes: "remove mixin injection as default, require Service Providers" for 4.0.
bpamiri commentedon Mar 16, 2026
Analysis
Synopsis
Replace the zip-based, mixin-injection plugin system with a Service Provider model in Wheels 4.0. Plugins would use
register(container)andboot(app)instead of having methods silently injected viaStructAppendinto component variable scopes.Merit Assessment
Recommendation: Proceed — this is the correct architectural direction, but the 3.x bridging issues must land first.
Plugins.cfcusesStructAppend(variablesScope, mixins, true)(line 313) to inject methods, meaning any two plugins defining the same method name silently overwrite each other. There is zero namespacing, zero collision detection, and zero warning. This is a real source of production bugs.Injector.cfc(297 lines) providesmap().to().asSingleton(),asRequestScoped(), auto-wiring, circular dependency detection, andonDIcomplete()callbacks. Theservice()andinjector()helpers inGlobal.cfc(lines 997-1027) give controllers/models access. The infrastructure for the Service Providerregister(container)call is already in place.Pipeline.cfcimplements thehandle(request, next)chain pattern.MiddlewareInterface.cfcdefines the contract. Theboot(app)method can register middleware viaapp.addMiddleware()without new pipeline work.Implementation Plan (Epic-Level)
The 3.x bridge work (Phase 3) must land before the 4.0 full transition. Here is the recommended sequencing:
Already done:
Injector.cfcis implemented and integratedPipeline.cfcandMiddlewareInterface.cfcexistPhase 1 — Foundation (3.x, do first):
plugin.jsonmanifest support. Extend$pluginMetaData()(Plugins.cfc lines 184-196) to readplugin.jsonalongsidebox.json. This unlocks declarative metadata for all subsequent features.Phase 2 — Lifecycle & DI (3.x, after Phase 1):
2. #1979 — Lifecycle hooks (
onPluginLoad,onPluginActivate). Modify$pluginsProcess()(lines 146-178) andonapplicationstart.cfc(lines 235-246).3. #1980 — Plugin DI integration via
services()method. Bridges legacy plugins to the container without requiring the full ServiceProvider pattern.Phase 3 — Service Provider Bridge (3.x, after Phase 2):
4. #1983 —
ServiceProviderInterfacewithregister(container)/boot(app). The key bridge component.5. #1984 — Deprecation warnings for mixin-only plugins in dev mode. Only meaningful after #1976 and #1983.
Phase 4 — Full 4.0 Transition:
6. #1966 — Module system and package format (replaces zip extraction)
7. #1967 — Interface-driven design contracts
8. #1968 — Engine adapter modules
9. #1969 — Legacy compatibility adapter (
wheels-legacy-plugin-adapter)Current Codebase State
Key files and their current responsibilities:
vendor/wheels/Plugins.cfcvendor/wheels/Injector.cfcvendor/wheels/middleware/Pipeline.cfcboot()vendor/wheels/middleware/MiddlewareInterface.cfcvendor/wheels/events/onapplicationstart.cfcvendor/wheels/Global.cfc:$loadPlugins()Mixable targets that currently receive injected methods:
application, dispatch, controller, mapper, model, base, sqlserver, mysql, postgresql, h2, test(Plugins.cfc line 15).Dependencies & Risks
wheels-legacy-plugin-adapter(Wheels 4.0: Legacy compatibility adapter and migration path Issue #1969 #1969) is essential — it should shim the oldStructAppendbehavior for plugins that haven't migrated.boot(app)context definition: The epic referencesapp.addMiddleware()andapp.modelTrait()but neither API exists yet. Theboot()parameter needs a concrete definition — recommend a lightweightAppContext.cfcthat wraps the mapper, middleware pipeline, DI container, and a newmodelTrait()registration mechanism.vendor/wheels/tests/) has no plugin-specific test specs currently. Each phase should include tests — especially for dual-mode (legacy + ServiceProvider) plugins.Plugins.cfcalready has BoxLang-specific code paths (lines 53-85, 101-103, 138-139). Any new plugin loading logic must be tested on both Lucee and BoxLang.Automated analysis by @claude — review and adjust as needed.
bpamiri commentedon Mar 28, 2026
Resolved by Package System (PR #1995)
The package system that landed in PR #1995 (merged 2026-03-26) implements the full scope of this epic:
ServiceProviderInterfacewithregister()/boot()vendor/wheels/ServiceProviderInterface.cfcplugin.json)package.jsonwithprovidesdeclarations (mixins, services, middleware)packages/→vendor/activation model via copy or symlinkregister(container)provides.middlewarein manifest +boot(app)controller,view,model,global,noneThree first-party packages shipped as proof: wheels-sentry, wheels-hotwire, wheels-basecoat — all with tests and CI.
The 3.x bridging sub-issues (#1975–#1984) were also closed as resolved.
Remaining Wheels 4.0 work (tracked separately)
These are orthogonal to the plugin→package transition and remain open.