re-add LDUser, allow SDK to accept it interchangeably with LDContext

Author: eli-darkly

Makefile

@@ -11,12 +11,10 @@ TEMP_TEST_OUTPUT=/tmp/sse-contract-test-service.log
 
 # TEST_HARNESS_PARAMS can be set to add -skip parameters for any contract tests that cannot yet pass
 # Explanation of current skips:
-# - "evaluation/bucketing/secondary": The "secondary" behavior needs to be removed from contract tests.
 # - "evaluation/parameterized/attribute references/array index is not supported": Due to how PHP
 #   arrays work, there's no way to disallow an array index lookup without breaking object property
 #   lookups for properties that are numeric strings.
 TEST_HARNESS_PARAMS := $(TEST_HARNESS_PARAMS) \
-	-skip 'evaluation/bucketing/secondary' \
 	-skip 'evaluation/parameterized/attribute references/array index is not supported'
 
 build-contract-tests:

src/LaunchDarkly/LDClient.php

@@ -178,12 +178,12 @@ private function getFeatureRequester(string $sdkKey, array $options): FeatureReq
      * does not match any existing flag), `$defaultValue` is returned.
      *
      * @param string $key the unique key for the feature flag
-     * @param LDContext $context the evaluation context
+     * @param LDContext|LDUser $context the evaluation context
      * @param mixed $defaultValue the default value of the flag
      * @return mixed the variation for the given context, or `$defaultValue` if the flag cannot be evaluated
      * @see \LaunchDarkly\LDClient::variationDetail()
      */
-    public function variation(string $key, LDContext $context, mixed $defaultValue = false): mixed
+    public function variation(string $key, LDContext|LDUser $context, mixed $defaultValue = false): mixed
     {
         $detail = $this->variationDetailInternal($key, $context, $defaultValue, $this->_eventFactoryDefault);
         return $detail->getValue();
@@ -197,27 +197,28 @@ public function variation(string $key, LDContext $context, mixed $defaultValue =
      * detailed event data for this flag.
      *
      * @param string $key the unique key for the feature flag
-     * @param LDContext $context the evaluation context
+     * @param LDContext|LDUser $context the evaluation context
      * @param mixed $defaultValue the default value of the flag
      *
      * @return EvaluationDetail an EvaluationDetail object that includes the feature flag value
      * and evaluation reason
      */
-    public function variationDetail(string $key, LDContext $context, mixed $defaultValue = false): EvaluationDetail
+    public function variationDetail(string $key, LDContext|LDUser $context, mixed $defaultValue = false): EvaluationDetail
     {
         return $this->variationDetailInternal($key, $context, $defaultValue, $this->_eventFactoryWithReasons);
     }
 
     /**
      * @param string $key
-     * @param LDContext $context
+     * @param LDContext|LDUser $contextOrUser
      * @param mixed $default
      * @param EventFactory $eventFactory
      *
      * @return EvaluationDetail
      */
-    private function variationDetailInternal(string $key, LDContext $context, mixed $default, EventFactory $eventFactory): EvaluationDetail
+    private function variationDetailInternal(string $key, LDContext|LDUser $contextOrUser, mixed $default, EventFactory $eventFactory): EvaluationDetail
     {
+        $context = $contextOrUser instanceof LDUser ? LDContext::fromUser($contextOrUser) : $contextOrUser;
         $default = $this->_get_default($key, $default);
 
         $errorDetail = fn (string $errorKind): EvaluationDetail =>
@@ -297,14 +298,15 @@ public function isOffline(): bool
      * Tracks that a user performed an event.
      *
      * @param string $eventName The name of the event
-     * @param LDContext $context The user that performed the event
+     * @param LDContext|LDUser $context The evaluation context associated with the event
      * @param mixed $data Optional additional information to associate with the event
      * @param int|float|null $metricValue A numeric value used by the LaunchDarkly experimentation feature in
      *   numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This
      *   field will also be returned as part of the custom event for Data Export.
      */
-    public function track(string $eventName, LDContext $context, mixed $data = null, int|float|null $metricValue = null): void
+    public function track(string $eventName, LDContext|LDUser $context, mixed $data = null, int|float|null $metricValue = null): void
     {
+        $context = $context instanceof LDUser ? LDContext::fromUser($context) : $context;
         if (!$context->isValid()) {
             $this->_logger->warning("Track called with null/empty user key!");
             return;
@@ -318,11 +320,12 @@ public function track(string $eventName, LDContext $context, mixed $data = null,
      * This simply registers the given user properties with LaunchDarkly without evaluating a feature flag.
      * This also happens automatically when you evaluate a flag.
      *
-     * @param LDContext $context The user properties
+     * @param LDContext|LDUser $context The user properties
      * @return void
      */
-    public function identify(LDContext $context): void
+    public function identify(LDContext|LDUser $context): void
     {
+        $context = $context instanceof LDUser ? LDContext::fromUser($context) : $context;
         if (!$context->isValid()) {
             $this->_logger->warning("Identify called with null/empty user key!");
             return;
@@ -339,7 +342,7 @@ public function identify(LDContext $context): void
      *
      * This method does not send analytics events back to LaunchDarkly.
      *
-     * @param LDContext $context the evalation context
+     * @param LDContext|LDUser $context the evalation context
      * @param array $options Optional properties affecting how the state is computed:
      * - `clientSideOnly`: Set this to true to specify that only flags marked for client-side use
      * should be included; by default, all flags are included
@@ -351,8 +354,9 @@ public function identify(LDContext $context): void
      *
      * @return FeatureFlagsState a FeatureFlagsState object (will never be null)
      */
-    public function allFlagsState(LDContext $context, array $options = []): FeatureFlagsState
+    public function allFlagsState(LDContext|LDUser $context, array $options = []): FeatureFlagsState
     {
+        $context = $context instanceof LDUser ? LDContext::fromUser($context) : $context;
         if (!$context->isValid()) {
             $error = $context->getError();
             $this->_logger->warning("Invalid context for allFlagsState ($error); returning empty state");
@@ -395,11 +399,12 @@ public function allFlagsState(LDContext $context, array $options = []): FeatureF
      *
      * See: [Secure mode](https://docs.launchdarkly.com/sdk/features/secure-mode)
      *
-     * @param LDContext $context the evaluation context
+     * @param LDContext|LDUser $context the evaluation context
      * @return string the hash value
      */
-    public function secureModeHash(LDContext $context): string
+    public function secureModeHash(LDContext|LDUser $context): string
     {
+        $context = $context instanceof LDUser ? LDContext::fromUser($context) : $context;
         if (!$context->isValid()) {
             return "";
         }

src/LaunchDarkly/LDContext.php

@@ -10,6 +10,10 @@
  * A collection of attributes that can be referenced in flag evaluations and analytics events.
  * This entity is also called an "evaluation context."
  *
+ * LDContext is the newer replacement for the previous, less flexible {@see \LaunchDarkly\LDUser} type.
+ * The current SDK still supports LDUser, but LDContext is now the preferred model and may entirely
+ * replace User in the future.
+ *
  * To create an LDContext of a single kind, such as a user, you may use
  * {@see \LaunchDarkly\LDContext::create()} when only the key and the kind are relevant; or, to
  * specify other attributes, use {@see \LaunchDarkly\LDContext::builder()}.
@@ -197,6 +201,58 @@ public static function createMulti(LDContext ...$contexts): LDContext
         return $b->build();
     }
 
+    /**
+     * @param LDUser $user
+     * @return LDContext
+     */
+    public static function fromUser(LDUser $user): LDContext
+    {
+        $attrs = null;
+        self::maybeAddAttr($attrs, "avatar", $user->getAvatar());
+        self::maybeAddAttr($attrs, "country", $user->getCountry());
+        self::maybeAddAttr($attrs, "email", $user->getEmail());
+        self::maybeAddAttr($attrs, "firstName", $user->getFirstName());
+        self::maybeAddAttr($attrs, "ip", $user->getIP());
+        self::maybeAddAttr($attrs, "lastName", $user->getLastName());
+        $userCustom = $user->getCustom();
+        if ($userCustom !== null && count($userCustom) !== 0) {
+            if ($attrs === null) {
+                $attrs = [];
+            }
+            foreach ($userCustom as $k => $v) {
+                $attrs[$k] = $v;
+            }
+        }
+        $privateAttrs = null;
+        $userPrivate = $user->getPrivateAttributeNames();
+        if ($userPrivate !== null && count($userPrivate) !== 0) {
+            $privateAttrs = [];
+            foreach ($userPrivate as $pa) {
+                $privateAttrs[] = AttributeReference::fromLiteral($pa);
+            }
+        }
+        return new LDContext(
+            self::DEFAULT_KIND,
+            $user->getKey(),
+            $user->getName(),
+            $user->getAnonymous() ?? false,
+            $attrs,
+            $privateAttrs,
+            null,
+            null
+        );
+    }
+
+    private static function maybeAddAttr(?array &$attrsOut, string $name, ?string $value): void
+    {
+        if ($value !== null) {
+            if ($attrsOut === null) {
+                $attrsOut = [];
+            }
+            $attrsOut[$name] = $value;
+        }
+    }
+
     /**
      * Creates a builder for building an LDContext.
      *

src/LaunchDarkly/LDUser.php

@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaunchDarkly;
+
+/**
+ * Contains specific attributes of a user browsing your site.
+ *
+ * LDUser supports only a subset of the behaviors that are available with the newer {@see \LaunchDarkly\LDContext}
+ * type. An LDUser is equivalent to an individual LDContext that has a `kind` of {@see \LaunchDarkly\LDContext::DEFAULT_KIND};
+ * it also has more constraints on attribute values than LDContext does (for instance, built-in attributes such as
+ * {@see \LaunchDarkly\LDUserBuilder::email()} can only have string values). Older LaunchDarkly SDKs only had the
+ * LDUser model, and the LDUser type has been retained for backward compatibility, but it may be removed in a
+ * future SDK version. Therefore, developers are recommended to migrate toward using LDContext.
+ *
+ * The only mandatory property property is the key, which must uniquely identify each user. For authenticated users,
+ * this may be a username or e-mail address. For anonymous users, it could be an IP address or session ID.
+ *
+ * Use {@see \LaunchDarkly\LDUserBuilder} to construct instances of this class.
+ */
+class LDUser
+{
+    protected string $_key;
+    protected ?string $_ip = null;
+    protected ?string $_country = null;
+    protected ?string $_email = null;
+    protected ?string $_name = null;
+    protected ?string $_avatar = null;
+    protected ?string $_firstName = null;
+    protected ?string $_lastName = null;
+    protected ?bool $_anonymous = false;
+    protected ?array $_custom = [];
+    protected ?array $_privateAttributeNames = [];
+
+    /**
+     * Constructor for directly creating an instance.
+     *
+     * It is preferable to use {@see LDUserBuilder} instead of this constructor.
+     *
+     * @param string $key Unique key for the user. For authenticated users, this may be a username or e-mail address. For anonymous users, this could be an IP address or session ID.
+     * @param string|null $secondary Obsolete parameter that is ignored if present, retained to avoid breaking code that called this constructor
+     * @param string|null $ip The user's IP address (optional)
+     * @param string|null $country The user's country, as an ISO 3166-1 alpha-2 code (e.g. 'US') (optional)
+     * @param string|null $email The user's e-mail address (optional)
+     * @param string|null $name The user's full name (optional)
+     * @param string|null $avatar A URL pointing to the user's avatar image (optional)
+     * @param string|null $firstName The user's first name (optional)
+     * @param string|null $lastName The user's last name (optional)
+     * @param bool|null $anonymous Whether this is an anonymous user
+     * @param array|null $custom Other custom attributes that can be used to create custom rules
+     * @return LDUser
+     */
+    public function __construct(
+        string $key,
+        ?string $secondary = null,
+        ?string $ip = null,
+        ?string $country = null,
+        ?string $email = null,
+        ?string $name = null,
+        ?string $avatar = null,
+        ?string $firstName = null,
+        ?string $lastName = null,
+        ?bool $anonymous = null,
+        ?array $custom = [],
+        ?array $privateAttributeNames = []
+    ) {
+        $this->_key = $key;
+        $this->_ip = $ip;
+        $this->_country = $country;
+        $this->_email = $email;
+        $this->_name = $name;
+        $this->_avatar = $avatar;
+        $this->_firstName = $firstName;
+        $this->_lastName = $lastName;
+        $this->_anonymous = $anonymous;
+        $this->_custom = $custom;
+        $this->_privateAttributeNames = $privateAttributeNames;
+    }
+
+    /**
+     * Used internally in flag evaluation.
+     * @ignore
+     * @return mixed
+     */
+    public function getValueForEvaluation(?string $attr): mixed
+    {
+        if (is_null($attr)) {
+            return null;
+        }
+        switch ($attr) {
+            case "key":
+                return $this->_key;
+            case "ip":
+                return $this->_ip;
+            case "country":
+                return $this->_country;
+            case "email":
+                return $this->_email;
+            case "name":
+                return $this->_name;
+            case "avatar":
+                return $this->_avatar;
+            case "firstName":
+                return $this->_firstName;
+            case "lastName":
+                return $this->_lastName;
+            case "anonymous":
+                return $this->_anonymous;
+            default:
+                if ($this->_custom === null) {
+                    return null;
+                }
+                return $this->_custom[$attr] ?? null;
+        }
+    }
+
+    public function getCountry(): ?string
+    {
+        return $this->_country;
+    }
+
+    public function getCustom(): ?array
+    {
+        return $this->_custom;
+    }
+
+    public function getIP(): ?string
+    {
+        return $this->_ip;
+    }
+
+    public function getKey(): string
+    {
+        return $this->_key;
+    }
+
+    public function getEmail(): ?string
+    {
+        return $this->_email;
+    }
+
+    public function getName(): ?string
+    {
+        return $this->_name;
+    }
+
+    public function getAvatar(): ?string
+    {
+        return $this->_avatar;
+    }
+
+    public function getFirstName(): ?string
+    {
+        return $this->_firstName;
+    }
+
+    public function getLastName(): ?string
+    {
+        return $this->_lastName;
+    }
+
+    public function getAnonymous(): ?bool
+    {
+        return $this->_anonymous;
+    }
+
+    public function getPrivateAttributeNames(): ?array
+    {
+        return $this->_privateAttributeNames;
+    }
+    
+    public function isKeyBlank(): bool
+    {
+        return empty($this->_key);
+    }
+}