PHP Feature Flags

Documentación > Feature Flags > Feature Flags del lado del servidor > PHP Feature Flags

Descripción general

Esta página describe cómo instrumentar su aplicación PHP con el Datadog Feature Flags SDK. El SDK de PHP utiliza el Remote Configuration del Datadog SDK para recibir actualizaciones de Feature Flags en tiempo real.

El SDK de PHP proporciona dos API de aplicación:

Datadog PHP API: utilícela DDTrace\FeatureFlags\Client con aplicaciones PHP 7 o PHP 8.
OpenFeature adapter: utilícelo DDTrace\OpenFeature\DataDogProvider con aplicaciones PHP 8 que utilicen la API estándar OpenFeature.

La evaluación de Feature Flags es local y rápida. El SDK utiliza datos de configuración almacenados en caché localmente, por lo que no se producen solicitudes de red durante la evaluación.

Requisitos previos

Antes de configurar el PHP Feature Flags SDK, asegúrese de tener:

Datadog Agent con Remote Configuration habilitado
clave de API de Datadog configurada en el Agent
Datadog PHP SDK datadog/dd-trace versión 1.21.0 o posterior
Entorno de ejecución de PHP compatible: PHP 7 o posterior con Datadog PHP API, o PHP 8 o posterior con OpenFeature adapter
OpenFeature PHP SDK open-feature/sdk versión 2.1 o posterior, si utiliza OpenFeature adapter

Establezca las siguientes variables de entorno:

# Required: Enable the feature flags provider
export DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true

# Required: Enable Remote Configuration in the SDK
export DD_REMOTE_CONFIG_ENABLED=true

# Required: Service identification
export DD_SERVICE=<YOUR_SERVICE_NAME>
export DD_ENV=<YOUR_ENVIRONMENT>
export DD_VERSION=<YOUR_APP_VERSION>

# Required for flag evaluation metrics
export DD_METRICS_OTEL_ENABLED=true

El EXPERIMENTAL_ prefijo se conserva por compatibilidad con versiones anteriores; el proveedor en sí es estable.

Para configurar feature_flag.evaluations, incluida la versión requerida del rastreador y la configuración de OTLP del Agent, consulte [Configurar métricas de evaluación de marcadores del lado del servidor]]6. Para obtener más información sobre los gráficos disponibles, consulte [Feature Flag Graphs][7].

Instalación

Feature Flagging es proporcionado por Application Performance Monitoring (APM). Instale y configure el rastreador Datadog PHP siguiendo Tracing PHP Applications.

Si utiliza OpenFeature adapter en una aplicación PHP 8, instale el OpenFeature PHP SDK:

composer require open-feature/sdk:^2.1

Inicializar el SDK

Elija la API que coincida con su entorno de ejecución de PHP y la arquitectura de su aplicación.

PHP 7 y PHP 8: Datadog API

Utilice DDTrace\FeatureFlags\Client directamente en aplicaciones PHP 7 o PHP 8:

<?php

use DDTrace\FeatureFlags\Client;

$flags = new Client();

PHP 8: OpenFeature adapter

En aplicaciones PHP 8, puede registrar Datadog como proveedor OpenFeature:

<?php

require_once __DIR__ . '/vendor/autoload.php';

use DDTrace\OpenFeature\DataDogProvider;
use OpenFeature\OpenFeatureAPI;

$api = OpenFeatureAPI::getInstance();
$api->setProvider(new DataDogProvider());

$client = $api->getClient('my-service');

El proveedor OpenFeature devuelve valores predeterminados hasta que Remote Configuration entrega la configuración inicial de Feature Flags. Inicialice el proveedor al inicio de la aplicación para que la configuración de Flag tenga tiempo de cargarse antes de que la lógica de negocio evalúe las Flags.

Establezca el contexto de evaluación

Defina un contexto de evaluación que identifique al usuario o entidad para la segmentación de marcadores. La clave de segmentación se utiliza para una distribución de tráfico consistente, como lanzamientos porcentuales. Los atributos adicionales permiten reglas de segmentación, como “habilitar para usuarios en EE. UU.” o “habilitar para usuarios de nivel premium”.

Datadog API

Para la Datadog PHP API, pase el contexto como un arreglo con las claves targetingKey y attributes:

$context = [
    'targetingKey' => 'user-123',
    'attributes' => [
        'email' => 'user@example.com',
        'country' => 'US',
        'tier' => 'premium',
        'age' => 25,
    ],
];

Adaptador de OpenFeature

Para el adaptador de OpenFeature, utilice el EvaluationContext del SDK de PHP de OpenFeature:

use OpenFeature\implementation\flags\Attributes;
use OpenFeature\implementation\flags\EvaluationContext;

$context = new EvaluationContext(
    'user-123',
    new Attributes([
        'email' => 'user@example.com',
        'country' => 'US',
        'tier' => 'premium',
        'age' => 25,
    ])
);

Los atributos del contexto de evaluación deben ser valores primitivos planos: cadenas, números y booleanos. Los arreglos anidados, los objetos y los valores nulos se ignoran para la segmentación y los informes de exposición.

Evaluar Feature Flags

Después de configurar el cliente, puede evaluar Feature Flags en toda su aplicación. Cada Feature Flag se identifica mediante una clave de cadena única y se evalúa con un método tipeado que devuelve un valor del tipo esperado. Si el Feature Flag no existe o no puede evaluarse, el SDK devuelve el valor predeterminado proporcionado.

Feature Flags booleanos

Utilice getBooleanValue para Feature Flags que representen condiciones de encendido/apagado o verdadero/falso:

$enabled = $flags->getBooleanValue('new-checkout-flow', false, $context);

if ($enabled) {
    showNewCheckout();
} else {
    showLegacyCheckout();
}

Con OpenFeature:

$enabled = $client->getBooleanValue('new-checkout-flow', false, $context);

Marcadores de cadena

Utilice getStringValue para Feature Flags que seleccionen entre variantes o cadenas de configuración:

$theme = $flags->getStringValue('ui-theme', 'light', $context);

switch ($theme) {
    case 'dark':
        setDarkTheme();
        break;
    case 'light':
    default:
        setLightTheme();
        break;
}

Marcadores numéricos

Para Feature Flags numéricas, utilice getIntegerValue o getFloatValue. Estos métodos son apropiados cuando una Feature Flag depende de un parámetro numérico como un límite, porcentaje o multiplicador:

$maxItems = $flags->getIntegerValue('cart-max-items', 20, $context);

$discountRate = $flags->getFloatValue('discount-rate', 0.0, $context);

Marcadores de objeto

Para datos estructurados, use getObjectValue. Esto devuelve un arreglo de PHP:

$config = $flags->getObjectValue('feature-config', [
    'maxRetries' => 3,
    'timeout' => 30,
], $context);

$maxRetries = $config['maxRetries'] ?? 3;
$timeout = $config['timeout'] ?? 30;

Detalles de evaluación de marcadores

Cuando necesite algo más que el valor de la Feature Flag, use los métodos get<Type>Details. Estos devuelven tanto el valor evaluado como los metadatos que explican la evaluación:

$details = $flags->getBooleanDetails('new-feature', false, $context);

printf("Value: %s\n", $details->getValue() ? 'true' : 'false');
printf("Variant: %s\n", $details->getVariant() ?? 'none');
printf("Reason: %s\n", $details->getReason());

if ($details->isError()) {
    printf("Error Code: %s\n", $details->getErrorCode());
    printf("Error Message: %s\n", $details->getErrorMessage());
}

Los detalles del marcador le ayudan a depurar el comportamiento de evaluación y a entender por qué un usuario recibió un valor determinado.

Ejemplos completos

Los siguientes ejemplos combinan la inicialización, el contexto de evaluación, la evaluación tipeada y los detalles de evaluación.

PHP 7 y PHP 8: Datadog API

<?php

use DDTrace\FeatureFlags\Client;

$flags = new Client();

$context = [
    'targetingKey' => 'user-123',
    'attributes' => [
        'country' => 'US',
        'tier' => 'premium',
    ],
];

$details = $flags->getStringDetails('checkout-copy', 'control', $context);

if ($details->isError()) {
    error_log(sprintf(
        'Flag evaluation failed: %s %s',
        $details->getErrorCode(),
        $details->getErrorMessage()
    ));
}

if ($details->getValue() === 'treatment') {
    showTreatmentCopy();
} else {
    showControlCopy();
}

PHP 8: OpenFeature adapter

<?php

require_once __DIR__ . '/vendor/autoload.php';

use DDTrace\OpenFeature\DataDogProvider;
use OpenFeature\implementation\flags\Attributes;
use OpenFeature\implementation\flags\EvaluationContext;
use OpenFeature\OpenFeatureAPI;

$api = OpenFeatureAPI::getInstance();
$api->setProvider(new DataDogProvider());

$client = $api->getClient('checkout-service', '1.0.0');
$context = new EvaluationContext(
    'user-123',
    new Attributes([
        'country' => 'US',
        'tier' => 'premium',
    ])
);

$details = $client->getStringDetails('checkout-copy', 'control', $context);
$error = $details->getError();

if ($error !== null) {
    error_log(sprintf(
        'Flag evaluation failed: %s %s',
        $error->getResolutionErrorCode()->getValue(),
        $error->getResolutionErrorMessage()
    ));
}

if ($details->getValue() === 'treatment') {
    showTreatmentCopy();
} else {
    showControlCopy();
}

Evaluación sin contexto

Puede evaluar Feature Flags sin proporcionar un contexto de evaluación. Esto es útil para Feature Flags globales que no requieren una segmentación específica del usuario:

$maintenanceMode = $flags->getBooleanValue('maintenance-mode', false);

if ($maintenanceMode) {
    http_response_code(503);
    echo 'Service temporarily unavailable';
    return;
}

Pruebas

Puede probar contra un entorno de prueba dedicado de Datadog con el proveedor real de Datadog, o reemplazar la evaluación de Feature Flags con un doble de prueba en las pruebas unitarias.

El OpenFeature PHP SDK 2.1 no incluye un proveedor in-memory incorporado. Para pruebas unitarias, envuelva la evaluación de Feature Flags detrás de una interfaz de aplicación e inyecte una implementación falsa:

FeatureFlags.php

<?php

use DDTrace\FeatureFlags\Client;

interface FeatureFlagReader
{
    public function getBooleanValue($flagKey, $defaultValue, array $context = []);
}

final class DatadogFeatureFlagReader implements FeatureFlagReader
{
    private $client;

    public function __construct(Client $client = null)
    {
        $this->client = $client ?: new Client();
    }

    public function getBooleanValue($flagKey, $defaultValue, array $context = [])
    {
        return $this->client->getBooleanValue($flagKey, $defaultValue, $context);
    }
}

final class InMemoryFeatureFlagReader implements FeatureFlagReader
{
    private $flags;

    public function __construct(array $flags)
    {
        $this->flags = $flags;
    }

    public function getBooleanValue($flagKey, $defaultValue, array $context = [])
    {
        return array_key_exists($flagKey, $this->flags)
            ? (bool) $this->flags[$flagKey]
            : $defaultValue;
    }
}

Utilice la implementación falsa en la configuración de su prueba:

CheckoutTest.php

$flags = new InMemoryFeatureFlagReader([
    'new-checkout-flow' => true,
]);

$checkout = new CheckoutService($flags);

self::assertTrue($checkout->usesNewCheckoutFlow('user-123'));

Solución de problemas

Feature Flags always return default values

Si las Feature Flags devuelven valores predeterminados de forma inesperada, verifique lo siguiente:

Verifique que DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true esté configurado en el entorno de su aplicación.
Verifique que Remote Configuration esté habilitado en la configuración de su Datadog Agent.
Asegúrese de que DD_SERVICE y DD_ENV estén configurados y coincidan con el servicio y el entorno configurados para su Feature Flag.
Confirme que su versión del Datadog PHP SDK incluya soporte para Feature Flags.
Verifique que el proceso de PHP pueda comunicarse con el Datadog Agent.

OpenFeature provider not found

El OpenFeature adapter solo está disponible para aplicaciones de PHP 8. Si no se encuentra DDTrace\OpenFeature\DataDogProvider:

Verifique que la aplicación se esté ejecutando en PHP 8 o una versión posterior.
Verifique que open-feature/sdk esté instalado a través de Composer.
Verifique que la versión del rastreador Datadog PHP incluya soporte para Feature Flags.

Las reglas de segmentación no coinciden con

Si las reglas de segmentación no coinciden como se esperaba:

Establezca un targetingKey estable para el usuario, la organización, la sesión o la entidad que se está evaluando.
Pase datos de segmentación personalizados bajo la clave attributes al usar Datadog API.
Utilice solo atributos primitivos planos. Los arreglos anidados, los objetos y los valores nulos se ignoran.
Verifique que el valor de DD_ENV aparezca en Feature Flag Environments.

Verifique las métricas y exposiciones de Feature Flags en Datadog

Métricas de evaluación de Feature Flags

Los conteos de evaluación de Feature Flags aparecen en Datadog cuando DD_METRICS_OTEL_ENABLED=true está configurado para el rastreador Datadog PHP. Cada evaluación emite una métrica de contador feature_flag.evaluations etiquetada con la clave de la Feature Flag, la variante del resultado y la razón de la evaluación. Si esta métrica no aparece, confirme que DD_METRICS_OTEL_ENABLED=true esté configurado en su entorno y que su versión del rastreador Datadog PHP admita métricas de evaluación de Feature Flags. Consulte Configurar métricas de evaluación de Feature Flags del lado del servidor para la configuración y solución de problemas del receptor OTLP del Datadog Agent.

Exposiciones de experimentos

Las exposiciones aparecen en Datadog solo para las Feature Flags asociadas con un experimento. Las Feature Flags estándar sin asociación a un experimento no generan eventos de exposición. Si faltan las exposiciones:

Verifique que la Feature Flag esté asociada con un experimento en la interfaz de usuario de Datadog.
Verifique que DD_API_KEY del Datadog Agent sea correcta y que el Datadog Agent esté recibiendo eventos.
Verifique que el contexto de evaluación utilice atributos primitivos planos. Los arreglos anidados, los objetos y los valores nulos se ignoran para los informes de exposición.