[FEATURE] Implement provider lifecycle, status, and events

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_READY
• READY
• STALE
• ERROR
• FATAL

Status must be updated before corresponding event handlers run.

Provider events

Provide a mechanism for providers to emit and consumers to handle:

• PROVIDER_READY
• PROVIDER_ERROR
• PROVIDER_STALE
• PROVIDER_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

• Provider initialization, shutdown, and status:
  https://openfeature.dev/specification/sections/providers/
• Provider lifecycle management:
  https://openfeature.dev/specification/sections/flag-evaluation/#provider-lifecycle-management
• Provider events:
  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_READY and PROVIDER_ERROR events while the SDK retains and deprecates the legacy synthetic behavior.

Relevant tests, examples, and documentation should be included.

Start with the current provider registration flow and OpenFeature API, then read the provider lifecycle and events specifications and the related issues #182 and #93. The work is done when lifecycle initialization and shutdown, provider status, event handlers, recovery, API shutdown, and backward compatibility are covered with relevant tests, examples, and documentation.