ServiceProvider interface — opt-in modern plugin contract #1983

Activity

1. bpamiri

   added

   enhancement

   on Mar 15, 2026
2. bpamiri commented on Mar 16, 2026

   

   bpamiri

   on Mar 16, 2026

   CollaboratorAuthor

   More actions

   Analysis

   Synopsis

   Introduce a ServiceProviderInterface with register(container) and boot(app) methods so plugins can opt into modern DI-backed lifecycle while legacy mixin plugins continue working unchanged. This is the 3.x bridge to the full Service Provider model in 4.0.

   Merit Assessment

   Recommendation: Proceed with modifications

   • Strong design: The dual-mode approach (ServiceProvider.cfc alongside legacy MyPlugin.cfc) is the right incremental strategy — it lets plugin authors migrate at their own pace without a flag day.
   • DI container is ready: Injector.cfc already supports map().to().asSingleton(), asRequestScoped(), auto-wiring, and is accessible via application.wheelsdi and the service() / injector() helpers in Global.cfc (lines 997-1027). The register(container) call can pass this directly.
   • Boot context needs definition: The boot(app) parameter is underspecified. The issue says "access to routes, middleware, events, and resolved services" but doesn't define what app actually is. This needs to be a concrete struct or facade, not just a loosely typed any. Recommendation: define an AppContext struct or lightweight CFC that wraps application.wheels.mapper, the middleware pipeline, the DI container, and config — this prevents plugins from reaching directly into application scope.
   • Ordering concern: The issue says "call register() in load order, then boot() in load order" but the current $pluginsProcess() sorts plugins alphabetically (line 148). This is fine for mixin injection but may be wrong for service providers where registration order matters. Consider adding an explicit priority or order field in plugin.json to control it.

   Implementation Plan

   1. Create vendor/wheels/ServiceProviderInterface.cfc — interface with register(required any container) and boot(required any app) methods, as specified in the issue.

   2. Modify vendor/wheels/Plugins.cfc:

      • Add variables.$class.serviceProviders = [] in $init() (line 12).
      • In $pluginsProcess() (lines 146-178), after instantiating each plugin at line 156, check for ServiceProvider.cfc in the plugin folder using FileExists(local.pluginValue.folderPath & "/ServiceProvider.cfc").
      • If found, instantiate it and store in variables.$class.serviceProviders.
      • Add new method $processServiceProviders() that loops through collected providers and calls register(application.wheelsdi).
      • Add $bootServiceProviders(app) that calls boot(app) on each.
      • Add getter getServiceProviders().

   3. Modify vendor/wheels/events/onapplicationstart.cfc:

      • After $loadPlugins() at line 237, call register() on all service providers (before mixin injection at line 241).
      • After routes and dispatcher are created (after line 256), call boot() on all service providers — this is where they get access to the mapper, middleware pipeline, and fully initialized DI container.

   4. Define the app context passed to boot():

      • At minimum: {container: application.wheelsdi, mapper: application.$wheels.mapper, config: application.$wheels, environment: application.$wheels.environment}.
      • Consider a thin AppContext.cfc facade for type safety and documentation.

   Estimated complexity: Medium. Core detection logic is ~40 lines in Plugins.cfc, bootstrap wiring is ~15 lines in onapplicationstart.cfc, plus the interface CFC.

   Dependencies & Risks

   • Hard dependency on Add plugin.json manifest support alongside box.json #1976 (plugin.json): The issue doesn't technically require plugin.json, but the dual-mode detection would benefit from a "serviceProvider": true manifest flag to avoid filesystem probing. Consider implementing Add plugin.json manifest support alongside box.json #1976 first or in parallel.
   • Soft dependency on Plugin lifecycle hooks: onPluginLoad, onPluginActivate #1979 (lifecycle hooks): The register()/boot() pattern supersedes the simpler onPluginLoad()/onPluginActivate() hooks. If both are implemented, the overlap needs clear documentation — service providers should NOT also get lifecycle hook calls to avoid double-initialization.
   • Soft dependency on Plugin DI integration — register services via Injector #1980 (DI integration): The register(container) method IS the DI integration for service providers. If Plugin DI integration — register services via Injector #1980's services() method is also implemented, plugins would have three ways to register services (mixin, services(), register()). Recommend Plugin DI integration — register services via Injector #1980 targets only legacy-style plugins, and service providers use register() exclusively.
   • No breaking changes: Legacy plugins without ServiceProvider.cfc continue to work identically.
   • Risk: The application.wheelsdi Injector is initialized via bindings CFC before plugins load, so the container will exist. However, plugins calling getInstance() during register() could fail if the dependency hasn't been registered yet — document that register() should only call map()/bind(), not getInstance().
   • Related: Plugin system → Service Provider model (Wheels 4.0) #1917 (epic), Wheels 4.0: Module system and package format #1966 (module system), Wheels 4.0: Interface-driven design contracts Issue #1967 #1967 (interface-driven design).

   ---

   Automated analysis by @claude — review and adjust as needed.

   👀React with 👀1Reacted by claude
3. bpamiri

   added

   phase:3-pluginsPlugin lifecycle, DI, middleware, migration bridgePlugin lifecycle, DI, middleware, migration bridge

   on Mar 16, 2026
4. bpamiri

   added this to the v3.2 milestone on Mar 17, 2026
5. bpamiri commented on Mar 26, 2026

   

   bpamiri

   on Mar 26, 2026

   CollaboratorAuthor

   More actions

   Implemented: ServiceProviderInterface.cfc with register(container) / boot(app) lifecycle. Wired into both Plugins.cfc and the new PackageLoader. Tested in ServiceProviderInterfaceSpec.cfc.
6. bpamiri

   closed this as completedon Mar 26, 2026