Merge pull request #82 from PostHog/feat/get-feature-flag-result

rafaeelaudibert · web-flow · commit 473796e8d8de · 2026-02-12T00:02:50.000-03:00
feat: Add `get_feature_flag_result`, `get_feature_flag_result!` API
diff --git a/.sampo/changesets/doughty-earl-erika.md b/.sampo/changesets/doughty-earl-erika.md
@@ -0,0 +1,5 @@
+---
+hex/posthog: minor
+---
+
+We've now added a new `get_feature_flag_result` method that can be used to get a full view of your feature flags including the payload rather than simply a boolean/string from the enabled/variant state.
diff --git a/README.md b/README.md
@@ -148,7 +148,7 @@ iex> PostHog.FeatureFlags.check("example-feature-flag-3", "user123")
 {:error, %PostHog.UnexpectedResponseError{message: "Feature flag example-feature-flag-3 was not found in the response", response: ...}}
 ```
 
-If you're feeling adventurous and/or is simply writing a script you can use the `PostHog.FeatureFlags.check!/2` helper instead and it will return a boolean or raise an error.
+If you're feeling adventurous and/or simply writing a script, you can use the `PostHog.FeatureFlags.check!/2` helper instead and it will return a boolean or raise an error.
 
 ```elixir
 # Simple boolean feature flag
@@ -159,12 +159,45 @@ true
 iex> PostHog.FeatureFlags.check!("example-feature-flag-2", "user123")
 "variant2"
 
-
 # Raises error if feature flag doesn't exist
 iex> PostHog.FeatureFlags.check!("example-feature-flag-3", "user123")
 ** (PostHog.UnexpectedResponseError) Feature flag example-feature-flag-3 was not found in the response
 ```
 
+### Getting the Full Flag Result
+
+If you need more than just the value -- for example, the payload configured for a
+flag or variant -- use `PostHog.FeatureFlags.get_feature_flag_result/2`:
+
+```elixir
+iex> PostHog.FeatureFlags.get_feature_flag_result("my-flag", "user123")
+{:ok, %PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}}
+
+# Multivariant flag with a JSON payload
+iex> PostHog.FeatureFlags.get_feature_flag_result("my-experiment", "user123")
+{:ok, %PostHog.FeatureFlags.Result{key: "my-experiment", enabled: true, variant: "control", payload: %{"button_color" => "blue"}}}
+
+# Flag not found
+iex> PostHog.FeatureFlags.get_feature_flag_result("non-existent-flag", "user123")
+{:ok, nil}
+```
+
+By default this sends a `$feature_flag_called` event, which PostHog uses to
+track feature flag usage in your analytics, and to measure experiment exposure
+when the flag is linked to an A/B test. You can opt out with `send_event: false`:
+
+```elixir
+iex> PostHog.FeatureFlags.get_feature_flag_result("my-flag", "user123", send_event: false)
+{:ok, %PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}}
+```
+
+A bang variant is also available:
+
+```elixir
+iex> PostHog.FeatureFlags.get_feature_flag_result!("my-flag", "user123")
+%PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}
+```
+
 ## Error Tracking
 
 Error Tracking is enabled by default.
diff --git a/lib/posthog/feature_flags.ex b/lib/posthog/feature_flags.ex
@@ -125,37 +125,202 @@ defmodule PostHog.FeatureFlags do
   @spec check(PostHog.supervisor_name(), String.t(), PostHog.distinct_id() | map() | nil) ::
           {:ok, boolean()} | {:ok, String.t()} | {:error, Exception.t()}
   def check(name \\ PostHog, flag_name, distinct_id_or_body \\ nil) do
-    with {:ok, %{distinct_id: distinct_id} = body} <- body_for_flags(distinct_id_or_body),
-         {:ok, %{body: body}} <- flags(name, body) do
-      result =
-        case body do
-          %{"flags" => %{^flag_name => %{"variant" => variant}}} when not is_nil(variant) ->
-            {:ok, variant}
+    case evaluate_flag(name, flag_name, distinct_id_or_body, []) do
+      {:ok, %__MODULE__.Result{} = flag_result, _body} ->
+        {:ok, __MODULE__.Result.value(flag_result)}
 
-          %{"flags" => %{^flag_name => %{"enabled" => true}}} ->
-            {:ok, true}
+      {:ok, nil, body} ->
+        {:error,
+         %PostHog.UnexpectedResponseError{
+           response: body,
+           message: "Feature flag #{flag_name} was not found in the response"
+         }}
 
-          %{"flags" => %{^flag_name => _}} ->
-            {:ok, false}
+      {:error, reason, _body} ->
+        {:error, reason}
+    end
+  end
 
-          %{"flags" => _} ->
-            {:error,
-             %PostHog.UnexpectedResponseError{
-               response: body,
-               message: "Feature flag #{flag_name} was not found in the response"
-             }}
-        end
+  @doc false
+  def get_feature_flag_result(flag_name, distinct_id_or_body)
+      when not is_atom(flag_name) and not is_list(distinct_id_or_body),
+      do: get_feature_flag_result(PostHog, flag_name, distinct_id_or_body, [])
+
+  @doc false
+  def get_feature_flag_result(flag_name, distinct_id_or_body, opts)
+      when not is_atom(flag_name) and is_list(opts),
+      do: get_feature_flag_result(PostHog, flag_name, distinct_id_or_body, opts)
+
+  @doc """
+  Gets the full feature flag result including value and payload.
+
+  Returns `{:ok, %PostHog.FeatureFlags.Result{}}` on success, `{:ok, nil}` if the flag
+  is not found, or `{:error, reason}` on failure.
+
+  The `PostHog.FeatureFlags.Result` struct contains:
+  - `key` - The flag name
+  - `enabled` - Whether the flag is enabled
+  - `variant` - The variant string (nil for boolean flags)
+  - `payload` - The JSON payload configured for the flag (nil if not set)
+
+  By default, this function will
+  [send](https://posthog.com/docs/api/flags#step-3-send-a-feature_flag_called-event)
+  a `$feature_flag_called` event and
+  [set](https://posthog.com/docs/api/flags#step-2-include-feature-flag-information-when-capturing-events)
+  the `$feature/feature-flag-name` property in context.
+
+  ## Options
+
+  - `:send_event` - Whether to send the `$feature_flag_called` event. Defaults to `true`.
+
+  ## Examples
+
+  Get feature flag result for `distinct_id`:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result("example-feature-flag-1", "user123")
+      {:ok, %PostHog.FeatureFlags.Result{key: "example-feature-flag-1", enabled: true, variant: nil, payload: nil}}
+
+  Get feature flag result with payload:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result("feature-with-payload", "user123")
+      {:ok, %PostHog.FeatureFlags.Result{key: "feature-with-payload", enabled: true, variant: "variant1", payload: %{"key" => "value"}}}
+
+  Get feature flag result without sending event:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result("my-flag", "user123", send_event: false)
+      {:ok, %PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}}
+
+  Flag not found returns `{:ok, nil}`:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result("non-existent-flag", "user123")
+      {:ok, nil}
+
+  Get feature flag result for `distinct_id` in the current context:
 
-      evaluated_at = Map.get(body, "evaluatedAt")
+      iex> PostHog.set_context(%{distinct_id: "user123"})
+      iex> PostHog.FeatureFlags.get_feature_flag_result("example-feature-flag-1")
+      {:ok, %PostHog.FeatureFlags.Result{key: "example-feature-flag-1", enabled: true, variant: nil, payload: nil}}
+
+  Get feature flag result through a named PostHog instance:
+
+      PostHog.FeatureFlags.get_feature_flag_result(MyPostHog, "example-feature-flag-1", "user123")
+  """
+  @spec get_feature_flag_result(
+          PostHog.supervisor_name(),
+          String.t(),
+          PostHog.distinct_id() | map() | nil,
+          keyword()
+        ) ::
+          {:ok, __MODULE__.Result.t() | nil} | {:error, Exception.t()}
+  def get_feature_flag_result(name \\ PostHog, flag_name, distinct_id_or_body \\ nil, opts \\ []) do
+    case evaluate_flag(name, flag_name, distinct_id_or_body, opts) do
+      {:ok, %__MODULE__.Result{} = result, _body} -> {:ok, result}
+      {:ok, nil, _body} -> {:ok, nil}
+      {:error, reason, _body} -> {:error, reason}
+    end
+  end
+
+  @doc false
+  def get_feature_flag_result!(flag_name, distinct_id_or_body)
+      when not is_atom(flag_name) and not is_list(distinct_id_or_body),
+      do: get_feature_flag_result!(PostHog, flag_name, distinct_id_or_body, [])
+
+  @doc false
+  def get_feature_flag_result!(flag_name, distinct_id_or_body, opts)
+      when not is_atom(flag_name) and is_list(opts),
+      do: get_feature_flag_result!(PostHog, flag_name, distinct_id_or_body, opts)
+
+  @doc """
+  Gets the full feature flag result or raises on error.
+
+  This is a wrapper around `get_feature_flag_result/4` that returns the result
+  directly or raises an exception on error. This follows the Elixir convention
+  where functions ending with `!` raise exceptions instead of returning error
+  tuples.
+
+  Returns `nil` if the flag is not found (does not raise), consistent with
+  other PostHog SDKs.
+
+  > **Warning**: Use this function with care as it will raise an error if there
+  > are any API errors (e.g. missing `distinct_id`). For more resilient code,
+  > use `get_feature_flag_result/4` which returns `{:error, reason}` instead of
+  > raising.
+
+  ## Options
+
+  - `:send_event` - Whether to send the `$feature_flag_called` event. Defaults to `true`.
 
-      # Make sure we keep track of the feature flag usage for debugging purposes
-      # Users are NOT charged extra for this, but it's still good to have.
-      log_feature_flag_usage(name, distinct_id, flag_name, result, evaluated_at)
+  ## Examples
+
+  Get feature flag result for `distinct_id`:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result!("example-feature-flag-1", "user123")
+      %PostHog.FeatureFlags.Result{key: "example-feature-flag-1", enabled: true, variant: nil, payload: nil}
+
+  Returns `nil` when flag is not found:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result!("non-existent-flag", "user123")
+      nil
 
-      result
+  Raises an error when `distinct_id` is missing:
+
+      iex> PostHog.FeatureFlags.get_feature_flag_result!("example-feature-flag-1")
+      ** (PostHog.Error) distinct_id is required but wasn't explicitly provided or found in the context
+  """
+  @spec get_feature_flag_result!(
+          PostHog.supervisor_name(),
+          String.t(),
+          PostHog.distinct_id() | map() | nil,
+          keyword()
+        ) ::
+          __MODULE__.Result.t() | nil | no_return()
+  def get_feature_flag_result!(name \\ PostHog, flag_name, distinct_id_or_body \\ nil, opts \\ []) do
+    case get_feature_flag_result(name, flag_name, distinct_id_or_body, opts) do
+      {:ok, result} -> result
+      {:error, error} -> raise error
     end
   end
 
+  defp evaluate_flag(name, flag_name, distinct_id_or_body, opts) do
+    send_event = Keyword.get(opts, :send_event, true)
+
+    with {:ok, %{distinct_id: distinct_id} = body} <- body_for_flags(distinct_id_or_body),
+         {:ok, %{body: body}} <- flags(name, body) do
+      case body do
+        %{"flags" => %{^flag_name => flag_data}} ->
+          {enabled, variant} = extract_flag_enabled_and_variant(flag_data)
+          payload = get_in(flag_data, ["metadata", "payload"])
+
+          flag_result = %__MODULE__.Result{
+            key: flag_name,
+            enabled: enabled,
+            variant: variant,
+            payload: payload
+          }
+
+          evaluated_at = Map.get(body, "evaluatedAt")
+
+          if send_event do
+            value = __MODULE__.Result.value(flag_result)
+            log_feature_flag_usage(name, distinct_id, flag_name, {:ok, value}, evaluated_at)
+          end
+
+          {:ok, flag_result, body}
+
+        %{"flags" => _} ->
+          {:ok, nil, body}
+      end
+    else
+      {:error, reason} -> {:error, reason, nil}
+    end
+  end
+
+  defp extract_flag_enabled_and_variant(flag_data) do
+    enabled = Map.get(flag_data, "enabled", false) == true
+    variant = Map.get(flag_data, "variant")
+    {enabled, variant}
+  end
+
   @doc false
   def check!(flag_name, distinct_id_or_body) when not is_atom(flag_name),
     do: check!(PostHog, flag_name, distinct_id_or_body)
@@ -238,7 +403,7 @@ defmodule PostHog.FeatureFlags do
             {:error,
              %PostHog.Error{
                message:
-                 "distinct_id is required but wasn't explicitely provided or found in the context"
+                 "distinct_id is required but wasn't explicitly provided or found in the context"
              }}
         end
 
diff --git a/lib/posthog/feature_flags/result.ex b/lib/posthog/feature_flags/result.ex
@@ -0,0 +1,66 @@
+defmodule PostHog.FeatureFlags.Result do
+  @moduledoc """
+  Represents the result of a feature flag evaluation.
+
+  This struct contains all the information returned when evaluating a feature flag:
+  - `key` - The name of the feature flag
+  - `enabled` - Whether the flag is enabled for this user
+  - `variant` - The variant assigned to this user (nil for boolean flags)
+  - `payload` - The JSON payload configured for this flag/variant (nil if not set)
+
+  ## Examples
+
+      # Boolean flag result
+      %PostHog.FeatureFlags.Result{
+        key: "my-feature",
+        enabled: true,
+        variant: nil,
+        payload: nil
+      }
+
+      # Multivariant flag result with payload
+      %PostHog.FeatureFlags.Result{
+        key: "my-experiment",
+        enabled: true,
+        variant: "control",
+        payload: %{"button_color" => "blue"}
+      }
+  """
+
+  @type json :: String.t() | number() | boolean() | nil | [json()] | %{String.t() => json()}
+
+  @type t :: %__MODULE__{
+          key: String.t(),
+          enabled: boolean(),
+          variant: String.t() | nil,
+          payload: json()
+        }
+
+  @enforce_keys [:key, :enabled]
+  defstruct [:key, :enabled, :variant, :payload]
+
+  @doc """
+  Returns the value of the feature flag result.
+
+  If a variant is present, returns the variant string. Otherwise, returns the
+  enabled boolean status. This provides backwards compatibility with existing
+  code that expects a simple value from feature flag checks.
+
+  ## Examples
+
+      iex> result = %PostHog.FeatureFlags.Result{key: "flag", enabled: true, variant: "control", payload: nil}
+      iex> PostHog.FeatureFlags.Result.value(result)
+      "control"
+
+      iex> result = %PostHog.FeatureFlags.Result{key: "flag", enabled: true, variant: nil, payload: nil}
+      iex> PostHog.FeatureFlags.Result.value(result)
+      true
+
+      iex> result = %PostHog.FeatureFlags.Result{key: "flag", enabled: false, variant: nil, payload: nil}
+      iex> PostHog.FeatureFlags.Result.value(result)
+      false
+  """
+  @spec value(t()) :: boolean() | String.t()
+  def value(%__MODULE__{variant: variant}) when not is_nil(variant), do: variant
+  def value(%__MODULE__{enabled: enabled}), do: enabled
+end
diff --git a/test/posthog/feature_flags/result_test.exs b/test/posthog/feature_flags/result_test.exs
diff --git a/test/posthog/feature_flags_test.exs b/test/posthog/feature_flags_test.exs

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +hex/posthog: minor
 +---
++
 +We've now added a new `get_feature_flag_result` method that can be used to get a full view of your feature flags including the payload rather than simply a boolean/string from the enabled/variant state.