Merge pull request #122 from launchdarkly/eb/sc-177541/re-add-user

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 or user
      * @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
+     * @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 or user
      * @param mixed $defaultValue the default value of the flag
      *
-     * @return EvaluationDetail an EvaluationDetail object that includes the feature flag value
+     * @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 =>
@@ -294,17 +295,24 @@ public function isOffline(): bool
     }
 
     /**
-     * Tracks that a user performed an event.
+     * Tracks that an application-defined event occurred.
+     *
+     * This method creates a "custom" analytics event containing the specified event name (key)
+     * and context properties. You may attach arbitrary data or a metric value to the event with the
+     * optional `data` and `metricValue` parameters.
+     *
+     * Note that event delivery is asynchronous, so the event may not actually be sent until later;
+     * see {@see \LaunchDarkly\LDClient::flush()}.
      *
      * @param string $eventName The name of the event
-     * @param LDContext $context The user that performed the event
+     * @param LDContext|LDUser $context The evaluation context or user 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.
+     *   numeric custom metrics; can be omitted if this event is used by only non-numeric metrics
      */
-    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;
@@ -313,16 +321,22 @@ public function track(string $eventName, LDContext $context, mixed $data = null,
     }
 
     /**
-     * Reports details about a user.
+     * Reports details about an evaluation context or user.
+     *
+     * This method simply creates an analytics event containing the context properties, to
+     * that LaunchDarkly will know about that context if it does not already.
      *
-     * This simply registers the given user properties with LaunchDarkly without evaluating a feature flag.
-     * This also happens automatically when you evaluate a flag.
+     * Evaluating a flag, by calling {@see \LaunchDarkly\LDClient::variation()} or
+     * {@see \LaunchDarkly\LDClient::variationDetail()} :func:`variation_detail()`, also sends
+     * the context information to LaunchDarkly (if events are enabled), so you only need to use
+     * identify() if you want to identify the context without evaluating a flag.
      *
-     * @param LDContext $context The user properties
+     * @param LDContext|LDUser $context The context or user to register
      * @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 +353,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 or user
      * @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 +365,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 +410,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
-     * @return string the hash value
+     * @param LDContext|LDUser $context The evaluation context or user
+     * @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

@@ -6,10 +6,33 @@
 
 use LaunchDarkly\Types\AttributeReference;
 
+function isAllowableUserCustomAttr(string $name): bool
+{
+    switch ($name) {
+        case 'anonymous':
+        case 'avatar':
+        case 'country':
+        case 'email':
+        case 'firstName':
+        case 'ip':
+        case 'key':
+        case 'kind':
+        case 'lastName':
+        case 'name':
+            return false;
+        default:
+            return true;
+    }
+}
+
 /**
  * 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 +220,60 @@ 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) {
+                if (isAllowableUserCustomAttr($k)) {
+                    $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.
      *
@@ -754,9 +831,6 @@ private static function decodeJsonSingleKind(array $o, ?string $kind): LDContext
 
     private static function decodeJsonOldUser(array $o, bool $wasParsedAsArray): LDContext
     {
-        $j = json_encode($o);
-        file_put_contents('php://stderr', "decodeJsonOldUser($j, $wasParsedAsArray)\n", FILE_APPEND);
-
         $b = self::builder('');
         $key = null;
         foreach ($o as $k => $v) {
@@ -770,7 +844,9 @@ private static function decodeJsonOldUser(array $o, bool $wasParsedAsArray): LDC
                             throw self::parsingBadTypeError($k);
                         }
                         foreach ((array)$v as $k1 => $v1) {
-                            $b->set($k1, $v1);
+                            if (isAllowableUserCustomAttr($k1)) {
+                                $b->set($k1, $v1);
+                            }
                         }
                     }
                     break;

src/LaunchDarkly/LDContextBuilder.php

@@ -97,7 +97,7 @@ public function key(string $key): LDContextBuilder
     /**
      * Sets the context's kind attribute.
      *
-     * Every LDContext has a kind. Setting it to an empty string or null is equivalent to
+     * Every context has a kind. Setting it to an empty string or null is equivalent to
      * {@see \LaunchDarkly\LDContext::DEFAULT_KIND} ("user"). This value is case-sensitive.
      *
      * The meaning of the context kind is completely up to the application. Validation rules are