Requirements
Requirements
This is a dedicated tracking issue for the provider lifecycle and events prerequisites listed in #182. Related historical context is available in #93.
Problem
The PHP SDK currently cannot manage providers that require initialization or own background resources.
The current provider registration flow cannot:
- initialize a newly registered provider
- wait for initialization to succeed or fail
- shut down a replaced provider
- expose the provider’s current status
- receive and dispatch provider lifecycle events
This forces such providers to initialize during their first flag evaluation. It also prevents reliable cleanup when a provider is replaced and makes late readiness, stale configuration, and recovery invisible
through the OpenFeature API.
Required behavior
Provider lifecycle
- Define a backward-compatible mechanism for providers to implement initialization.
- Supply the global evaluation context and bound domain during initialization.
- Invoke initialization when the provider is registered.
- Provide a way to register a provider and wait for initialization to complete.
- Propagate initialization failure according to the OpenFeature specification.
- Invoke provider shutdown when it is replaced and no longer in use.
- Invoke provider shutdown when the OpenFeature API shuts down.
- Ensure shutdown is idempotent.
- Reset SDK state appropriately during API shutdown.
Provider status
Expose the status of the provider associated with a client:
NOT_READYREADYSTALEERRORFATAL
Status must be updated before corresponding event handlers run.
Provider events
Provide a mechanism for providers to emit and consumers to handle:
PROVIDER_READYPROVIDER_ERRORPROVIDER_STALEPROVIDER_CONFIGURATION_CHANGED
The API and clients should support adding and removing handlers.
Initialization and its resulting event must be coordinated so registration cannot complete before the corresponding status transition has been processed.
A provider that recovers after an initialization error must be able to emit PROVIDER_READY and transition back to READY.
Event ownership and backward compatibility
Adding required methods directly to the existing Provider interface would break existing provider implementations.
The implementation should preserve compatibility where possible, potentially using optional lifecycle/event interfaces or an opt-in marker as described in #182.
Lifecycle-aware providers should own their PROVIDER_READY and PROVIDER_ERROR events. Existing providers that do not opt in should retain compatible behavior during a transition period.
Specification references
Implementation considerations
The implementation should preserve backward compatibility for existing application and provider code, as requested in #93.
Issue #182 proposes an opt-in marker so lifecycle-aware providers can own their PROVIDER_READY and PROVIDER_ERROR events while the SDK retains and deprecates the legacy synthetic behavior.
Relevant tests, examples, and documentation should be included.
Requirements
Requirements
This is a dedicated tracking issue for the provider lifecycle and events prerequisites listed in #182. Related historical context is available in #93.
Problem
The PHP SDK currently cannot manage providers that require initialization or own background resources.
The current provider registration flow cannot:
This forces such providers to initialize during their first flag evaluation. It also prevents reliable cleanup when a provider is replaced and makes late readiness, stale configuration, and recovery invisible
through the OpenFeature API.
Required behavior
Provider lifecycle
Provider status
Expose the status of the provider associated with a client:
NOT_READYREADYSTALEERRORFATALStatus must be updated before corresponding event handlers run.
Provider events
Provide a mechanism for providers to emit and consumers to handle:
PROVIDER_READYPROVIDER_ERRORPROVIDER_STALEPROVIDER_CONFIGURATION_CHANGEDThe API and clients should support adding and removing handlers.
Initialization and its resulting event must be coordinated so registration cannot complete before the corresponding status transition has been processed.
A provider that recovers after an initialization error must be able to emit
PROVIDER_READYand transition back toREADY.Event ownership and backward compatibility
Adding required methods directly to the existing
Providerinterface would break existing provider implementations.The implementation should preserve compatibility where possible, potentially using optional lifecycle/event interfaces or an opt-in marker as described in #182.
Lifecycle-aware providers should own their
PROVIDER_READYandPROVIDER_ERRORevents. Existing providers that do not opt in should retain compatible behavior during a transition period.Specification references
https://openfeature.dev/specification/sections/providers/
https://openfeature.dev/specification/sections/flag-evaluation/#provider-lifecycle-management
https://openfeature.dev/specification/sections/events/
Implementation considerations
The implementation should preserve backward compatibility for existing application and provider code, as requested in #93.
Issue #182 proposes an opt-in marker so lifecycle-aware providers can own their
PROVIDER_READYandPROVIDER_ERRORevents while the SDK retains and deprecates the legacy synthetic behavior.Relevant tests, examples, and documentation should be included.