From d5f7306784e9fbb0493866ed1562c06fb5367b38 Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Tue, 13 Oct 2026 23:40:07 +0000 Subject: [PATCH 1/4] Document the PHP CDN configuration preview --- hugo/content/en/feature_flags/server/php.md | 54 +++++++++++++++++++-- 1 file changed, 49 insertions(+), 5 deletions(-) diff --git a/hugo/content/en/feature_flags/server/php.md b/hugo/content/en/feature_flags/server/php.md index 9a202db7c4d5..bdbdc52e9bb9 100644 --- a/hugo/content/en/feature_flags/server/php.md +++ b/hugo/content/en/feature_flags/server/php.md @@ -21,18 +21,18 @@ further_reading: ## Overview -This page describes how to instrument your PHP application with the Datadog Feature Flags SDK. The PHP SDK uses the Datadog SDK's Remote Configuration to receive flag updates in real time. +This page describes how to instrument your PHP application with the Datadog Feature Flags SDK. Released PHP SDKs receive flag updates through the Datadog Agent's Remote Configuration. The [agentless preview](#agentless-preview) reads configuration directly from Datadog. The PHP SDK provides two application APIs: - **Datadog PHP API**: Use `DDTrace\FeatureFlags\Client` with PHP 7 or PHP 8 applications. - **OpenFeature adapter**: Use `DDTrace\OpenFeature\DataDogProvider` with PHP 8 applications that use the [OpenFeature][1] standard API. -Flag evaluation is local and fast. The SDK uses locally cached configuration data, so no network requests occur during evaluation. +Flag evaluation uses locally cached configuration. In the agentless preview, the first evaluation can wait for the initial configuration within a bounded initialization timeout. -## Prerequisites +## Set up with an Agent -Before setting up the PHP Feature Flags SDK, ensure you have: +Before setting up the PHP Feature Flags SDK, you need: - **Datadog Agent** with [Remote Configuration][2] enabled - **Datadog [API key][3]** configured on the Agent @@ -62,6 +62,48 @@ export DD_METRICS_OTEL_ENABLED=true To configure `feature_flag.evaluations`, including the required tracer version and Agent OTLP setup, see [Set Up Server-Side Flag Evaluation Metrics][6]. For more information on available graphing, see [Feature Flag Graphs][7]. +## Agentless preview + +
Agentless configuration requires an unreleased PHP SDK candidate. Use a version that includes CDN configuration support; the release version has not been confirmed.
+ +The preview supports the Datadog PHP API and the OpenFeature adapter. Install a candidate that includes agentless configuration, then configure the PHP process: + +{{< code-block lang="bash" >}} +export DD_FEATURE_FLAGS_ENABLED=true +export DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless +export DD_API_KEY= +export DD_SITE= +export DD_SERVICE= +export DD_ENV= +export DD_VERSION= +{{< /code-block >}} + +Set these variables before starting PHP. For PHP-FPM, make them available to the worker processes and restart the pool after changes. Keep the API key in server-side secret storage. + +The SDK fetches configuration over HTTPS from `ufc-server.ff-cdn.` for `DD_ENV`. It uses the same application APIs and targeting contexts shown below. Feature flags can operate with `DD_TRACE_ENABLED=false`. + +### Configuration and initialization + +The first evaluation starts background polling and waits up to `DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS` (default: `10000`). Later evaluations share that initialization budget. If configuration is unavailable when the budget expires, evaluation returns the supplied default. Polling continues, so subsequent evaluations can recover. + +The SDK polls every 30 seconds by default, with a 5-second HTTP request timeout. Configure these intervals with `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` and `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS`. A failed request or invalid update retains the last valid configuration. An HTTP 304 response keeps that configuration. + +For a custom configuration service, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL`. A URL with only a root path uses `/api/v2/feature-flagging/config/rules-based/server`; a URL with a non-root path is requested as supplied. The SDK does not send the Datadog API key to a custom configuration URL. This setting changes configuration retrieval only; it does not redirect exposure or evaluation events. + +CDN configuration and polling belong to the PHP process. The SDK stops and joins its poller during process shutdown, and restarts independent pollers in the parent and child after a supported fork. The PHP application APIs do not expose a separate public flush or shutdown method. + +### Reporting + +This preview adds CDN configuration retrieval and local flag evaluation. It does not add direct intake or EVP fallback for experiment exposures or flag evaluation events. Keep the existing Agent and metric receiver configuration for reporting that is already supported. For `feature_flag.evaluations` OpenTelemetry metrics, see [Set Up Server-Side Flag Evaluation Metrics][6]. + +### Source selection and rollback + +An explicit `DD_FEATURE_FLAGS_ENABLED=false` disables the provider. Otherwise, an explicit `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=agentless` or `remote_config` selects the source. Invalid source values and the unsupported `offline` source disable the provider instead of silently changing routes. + +With no explicit source, `DD_FEATURE_FLAGS_ENABLED=true` selects agentless configuration. If the stable settings are unset, the legacy `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true` continues to select Remote Configuration; an explicit legacy `false` disables the provider. With neither stable nor legacy settings supplied, the preview defaults to agentless configuration and requires a valid managed endpoint configuration. + +To return to Agent-based operation, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE=remote_config`, enable `DD_REMOTE_CONFIG_ENABLED=true`, configure the Agent endpoint, and restart PHP. Remote Configuration mode uses Agent-only event delivery. To turn off feature flags, set `DD_FEATURE_FLAGS_ENABLED=false` and restart PHP. + ## Installation Feature Flagging is provided by Application Performance Monitoring (APM). Install and configure the Datadog PHP tracer by following [Tracing PHP Applications][4]. @@ -106,7 +148,7 @@ $api->setProvider(new DataDogProvider()); $client = $api->getClient('my-service'); {{< /code-block >}} -The OpenFeature provider returns default values until Remote Configuration delivers the initial flag configuration. Initialize the provider early in application startup so flag configuration has time to load before business logic evaluates flags. +In Remote Configuration mode, the OpenFeature provider returns default values until the Agent delivers the initial flag configuration. In the agentless preview, the first evaluation starts polling and applies the initialization timeout described above. Registering the OpenFeature provider alone does not fetch configuration. ## Set the evaluation context @@ -401,6 +443,8 @@ If feature flags unexpectedly always return default values, check the following: - Confirm your Datadog PHP SDK version includes feature flags support. - Check that the PHP process can communicate with the Datadog Agent. +For the agentless preview, check `DD_FEATURE_FLAGS_ENABLED`, the selected configuration source, `DD_API_KEY`, `DD_SITE`, and `DD_ENV`. Confirm that the PHP process can establish trusted HTTPS connections to the configuration endpoint. If only early evaluations return defaults, check the initialization timeout and whether a later evaluation recovers. + ### OpenFeature provider not found The OpenFeature adapter is available only for PHP 8 applications. If `DDTrace\OpenFeature\DataDogProvider` is not found: From 3af6c3bebaa01d7db4e3147cb248205fa5b57ca9 Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Wed, 14 Oct 2026 00:10:45 +0000 Subject: [PATCH 2/4] Restore the PHP flag graph documentation reference Environment: Datadog workspace --- hugo/content/en/feature_flags/server/php.md | 1 + 1 file changed, 1 insertion(+) diff --git a/hugo/content/en/feature_flags/server/php.md b/hugo/content/en/feature_flags/server/php.md index bdbdc52e9bb9..a3ae321de975 100644 --- a/hugo/content/en/feature_flags/server/php.md +++ b/hugo/content/en/feature_flags/server/php.md @@ -486,3 +486,4 @@ Exposures appear in Datadog only for flags associated with an experiment. Standa [4]: /tracing/trace_collection/dd_libraries/php/ [5]: /feature_flags/concepts/environments/ [6]: /feature_flags/guide/server_flag_evaluation_metrics/ +[7]: /feature_flags/concepts/flag_graphs/ From 7ccc73e393d52dd5fd729c5869034ac019d04184 Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Wed, 14 Oct 2026 14:50:50 +0000 Subject: [PATCH 3/4] Document subprocess requirements for PHP CDN configuration Environment: Datadog workspace --- hugo/content/en/feature_flags/server/php.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/hugo/content/en/feature_flags/server/php.md b/hugo/content/en/feature_flags/server/php.md index a3ae321de975..3c1e4e47225c 100644 --- a/hugo/content/en/feature_flags/server/php.md +++ b/hugo/content/en/feature_flags/server/php.md @@ -80,7 +80,7 @@ export DD_VERSION= Set these variables before starting PHP. For PHP-FPM, make them available to the worker processes and restart the pool after changes. Keep the API key in server-side secret storage. -The SDK fetches configuration over HTTPS from `ufc-server.ff-cdn.` for `DD_ENV`. It uses the same application APIs and targeting contexts shown below. Feature flags can operate with `DD_TRACE_ENABLED=false`. +The SDK starts a libdatadog sidecar subprocess that fetches configuration over HTTPS from `ufc-server.ff-cdn.` for `DD_ENV`. It uses the same application APIs and targeting contexts shown below. Feature flags can operate with `DD_TRACE_ENABLED=false`. ### Configuration and initialization @@ -90,7 +90,7 @@ The SDK polls every 30 seconds by default, with a 5-second HTTP request timeout. For a custom configuration service, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL`. A URL with only a root path uses `/api/v2/feature-flagging/config/rules-based/server`; a URL with a non-root path is requested as supplied. The SDK does not send the Datadog API key to a custom configuration URL. This setting changes configuration retrieval only; it does not redirect exposure or evaluation events. -CDN configuration and polling belong to the PHP process. The SDK stops and joins its poller during process shutdown, and restarts independent pollers in the parent and child after a supported fork. The PHP application APIs do not expose a separate public flush or shutdown method. +CDN requests run in the sidecar subprocess. PHP reads configuration through shared memory and evaluates locally. After a sidecar restart, PHP resubscribes while retaining the last valid configuration; after a supported fork, the parent and child resume their configuration readers. Polling stops when the last subscriber disconnects. Explicit `DD_TRACE_SIDECAR_CONNECTION_MODE=thread` does not support CDN configuration; use the default `auto` mode. The PHP application APIs do not expose a separate public flush or shutdown method. ### Reporting @@ -443,7 +443,7 @@ If feature flags unexpectedly always return default values, check the following: - Confirm your Datadog PHP SDK version includes feature flags support. - Check that the PHP process can communicate with the Datadog Agent. -For the agentless preview, check `DD_FEATURE_FLAGS_ENABLED`, the selected configuration source, `DD_API_KEY`, `DD_SITE`, and `DD_ENV`. Confirm that the PHP process can establish trusted HTTPS connections to the configuration endpoint. If only early evaluations return defaults, check the initialization timeout and whether a later evaluation recovers. +For the agentless preview, check `DD_FEATURE_FLAGS_ENABLED`, the selected configuration source, `DD_API_KEY`, `DD_SITE`, and `DD_ENV`. Confirm that PHP can start its sidecar subprocess and that the subprocess can establish trusted HTTPS connections to the configuration endpoint. If only early evaluations return defaults, check the initialization timeout and whether a later evaluation recovers. ### OpenFeature provider not found From 315d8b824e46b9939fdc9673bbbeb480892847e6 Mon Sep 17 00:00:00 2001 From: Leo Romanovsky Date: Wed, 14 Oct 2026 18:16:03 +0000 Subject: [PATCH 4/4] Document PHP CDN retries, response format and setup diagnostics --- hugo/content/en/feature_flags/server/php.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/hugo/content/en/feature_flags/server/php.md b/hugo/content/en/feature_flags/server/php.md index 3c1e4e47225c..16bbfff57314 100644 --- a/hugo/content/en/feature_flags/server/php.md +++ b/hugo/content/en/feature_flags/server/php.md @@ -88,8 +88,14 @@ The first evaluation starts background polling and waits up to `DD_EXPERIMENTAL_ The SDK polls every 30 seconds by default, with a 5-second HTTP request timeout. Configure these intervals with `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS` and `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS`. A failed request or invalid update retains the last valid configuration. An HTTP 304 response keeps that configuration. +Transient failures can trigger up to three attempts per poll. The SDK honors `Retry-After` on retryable HTTP responses when it requests a longer wait than the SDK's backoff. Process shutdown cancels that wait. + For a custom configuration service, set `DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL`. A URL with only a root path uses `/api/v2/feature-flagging/config/rules-based/server`; a URL with a non-root path is requested as supplied. The SDK does not send the Datadog API key to a custom configuration URL. This setting changes configuration retrieval only; it does not redirect exposure or evaluation events. +Custom services must return a JSON:API resource with `data.type` set to `universal-flag-configuration` and a UFC document in `data.attributes` with `format` set to `SERVER`. Invalid responses do not replace the cached configuration. The sidecar honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` from its startup environment. + +On first evaluation, invalid settings produce a redacted warning once per process. Invalid polling or timeout values use their defaults. Missing managed-endpoint credentials and invalid source, site, or URL settings return defaults with a specific error message in evaluation details. After correcting process settings, restart PHP. + CDN requests run in the sidecar subprocess. PHP reads configuration through shared memory and evaluates locally. After a sidecar restart, PHP resubscribes while retaining the last valid configuration; after a supported fork, the parent and child resume their configuration readers. Polling stops when the last subscriber disconnects. Explicit `DD_TRACE_SIDECAR_CONNECTION_MODE=thread` does not support CDN configuration; use the default `auto` mode. The PHP application APIs do not expose a separate public flush or shutdown method. ### Reporting