Merge pull request #24 from PostHog/add-enabled-flag

Author: rafaeelaudibert

CHANGELOG.md

@@ -10,6 +10,7 @@
 - Feature Flags now return a key called `payload` rather than `value` to better align with the other SDKs
 - PostHog now requires you to initialize `Posthog.Application` alongside your supervisor tree. This is required because of our `Cachex` system to properly track your FF usage.
   - We'll also include local evaluation in the near term, which will also require a GenServer, therefore, requiring us to use a Supervisor.
+- Added `enabled_capture` configuration option to disable PostHog tracking in development/test environments
 
 ## 0.4.4 - 2025-04-14
 

README.md

@@ -12,6 +12,7 @@ A powerful Elixir client for [PostHog](https://posthog.com), providing seamless
 - Batch Processing: Send multiple events efficiently
 - Custom Properties: Support for user, group, and person properties
 - Flexible Configuration: Customizable JSON library and API version
+- Environment Control: Disable tracking in development/test environments
 
 ## Installation
 
@@ -74,7 +75,38 @@ config :posthog,
 
 # Optional configurations
 config :posthog,
-  json_library: Jason  # Default JSON parser (optional)
+  json_library: Jason,  # Default JSON parser (optional)
+  enabled: true        # Whether to enable PostHog tracking (optional, defaults to true)
+```
+
+### Disabling PostHog capture
+
+You can disable PostHog tracking by setting `enabled_capture: false` in your configuration. This is particularly useful in development or test environments where you don't want to send actual events to PostHog.
+
+When `enabled_capture` is set to `false`:
+
+- All `Posthog.capture/3` and `Posthog.batch/3` calls will succeed silently
+- PostHog will still communicate with the server for Feature Flags
+
+This is useful for:
+
+- Development and test environments where you don't want to pollute your PostHog instance
+- Situations where you need to temporarily disable tracking
+
+Example configuration for development:
+
+```elixir
+# config/dev.exs
+config :posthog,
+  enabled_capture: false  # Disable tracking in development
+```
+
+Example configuration for test:
+
+```elixir
+# config/test.exs
+config :posthog,
+  enabled_capture: false  # Disable tracking in test environment
 ```
 
 ## Usage

lib/posthog.ex

@@ -22,8 +22,35 @@ defmodule Posthog do
   Optional configuration:
 
       config :posthog,
-        json_library: Jason,  # Default JSON parser (optional)
-        version: 3           # API version (optional, defaults to 3)
+        json_library: Jason,   # Default JSON parser (optional)
+        enabled_capture: true  # Whether to enable PostHog tracking (optional, defaults to true)
+                               # Set to false in development/test environments to disable tracking
+
+  ### Disabling PostHog
+
+  You can disable PostHog tracking by setting `enabled: false` in your configuration.
+  This is particularly useful in development or test environments where you don't want
+  to send actual events to PostHog.
+
+  When `enabled_capture` is set to `false`:
+  - All `Posthog.capture/3` and `Posthog.batch/3` calls will succeed silently
+  - PostHog will still communicate with the server for Feature Flags
+
+  This is useful for:
+  - Development and test environments where you don't want to pollute your PostHog instance
+  - Situations where you need to temporarily disable tracking
+
+  Example configuration for development:
+
+      # config/dev.exs
+      config :posthog,
+        enabled_capture: false  # Disable tracking in development
+
+  Example configuration for test:
+
+      # config/test.exs
+      config :posthog,
+        enabled_capture: false  # Disable tracking in test environment
 
   ## Event Tracking
 

lib/posthog/client.ex

@@ -19,7 +19,24 @@ defmodule Posthog.Client do
         api_url: "https://app.posthog.com",  # Required
         api_key: "phc_your_project_api_key", # Required
         json_library: Jason,                 # Optional (default: Jason)
-        version: 3                          # Optional (default: 3)
+        enabled_capture: true                # Optional (default: true)
+                                             # Set to false to disable all tracking
+
+  ### Disabling capture
+
+  When `enabled_capture` is set to `false`:
+  - All `Posthog.capture/3` and `Posthog.batch/3` calls will succeed silently
+  - PostHog will still communicate with the server for Feature Flags
+
+  This is useful for:
+  - Development and test environments where you don't want to pollute your PostHog instance
+  - Situations where you need to temporarily disable tracking
+
+  Example configuration for disabling the client:
+
+      # config/dev.exs or config/test.exs
+      config :posthog,
+        enabled_capture: false
 
   ## API Endpoints
 
@@ -154,11 +171,19 @@ defmodule Posthog.Client do
   @spec capture(event(), properties(), opts() | timestamp()) ::
           {:ok, response()} | {:error, response() | term()}
   def capture(event, params, opts) when is_list(opts) do
-    post!("/capture", build_event(event, params, opts[:timestamp]), headers(opts[:headers]))
+    if enabled_capture?() do
+      post!("/capture", build_event(event, params, opts[:timestamp]), headers(opts[:headers]))
+    else
+      disabled_capture_response()
+    end
   end
 
   def capture(event, params, timestamp) when is_bitstring(event) or is_atom(event) do
-    post!("/capture", build_event(event, params, timestamp), headers())
+    if enabled_capture?() do
+      post!("/capture", build_event(event, params, timestamp), headers())
+    else
+      disabled_capture_response()
+    end
   end
 
   @doc """
@@ -186,9 +211,12 @@ defmodule Posthog.Client do
   end
 
   def batch(events, _opts, headers) do
-    body = for {event, params, timestamp} <- events, do: build_event(event, params, timestamp)
-
-    post!("/capture", %{batch: body}, headers)
+    if enabled_capture?() do
+      body = for {event, params, timestamp} <- events, do: build_event(event, params, timestamp)
+      post!("/capture", %{batch: body}, headers)
+    else
+      disabled_capture_response()
+    end
   end
 
   @doc """
@@ -388,6 +416,15 @@ defmodule Posthog.Client do
     end
   end
 
+  @doc false
+  defp enabled_capture? do
+    Application.get_env(@app, :enabled_capture, true)
+  end
+
+  defp disabled_capture_response do
+    {:ok, %{status: 200, headers: [], body: nil}}
+  end
+
   @doc false
   @spec encode(term(), module()) :: iodata()
   defp encode(data, Jason), do: Jason.encode_to_iodata!(data)

test/posthog/client_test.exs

@@ -1,5 +1,6 @@
 defmodule Posthog.ClientTest do
   use ExUnit.Case, async: true
+  import Mimic
 
   # Make private functions testable
   @moduletag :capture_log
@@ -129,4 +130,38 @@ defmodule Posthog.ClientTest do
                )
     end
   end
+
+  describe "enabled_capture" do
+    test "when enabled_capture is false, capture returns success without making request" do
+      Application.put_env(:posthog, :enabled_capture, false)
+      on_exit(fn -> Application.delete_env(:posthog, :enabled_capture) end)
+
+      assert Client.capture("test_event", %{distinct_id: "user_123"}, []) ==
+               {:ok, %{status: 200, headers: [], body: nil}}
+    end
+
+    test "when enabled_capture is false, batch returns success without making request" do
+      Application.put_env(:posthog, :enabled_capture, false)
+      on_exit(fn -> Application.delete_env(:posthog, :enabled_capture) end)
+
+      events = [
+        {"test_event", %{distinct_id: "user_123"}, nil},
+        {"another_event", %{distinct_id: "user_123"}, nil}
+      ]
+
+      assert Client.batch(events, []) ==
+               {:ok, %{status: 200, headers: [], body: nil}}
+    end
+
+    test "when enabled_capture is false, feature_flags still works" do
+      Application.put_env(:posthog, :enabled_capture, false)
+      on_exit(fn -> Application.delete_env(:posthog, :enabled_capture) end)
+
+      # Stub FF HTTP request
+      stub_with(:hackney, HackneyStub)
+
+      assert {:ok, %{feature_flags: flags}} = Client.feature_flags("user_123", [])
+      assert flags["my-awesome-flag"] == true
+    end
+  end
 end