references/adding-feature-flag-code.md · 24000
t_feature_flag_payload(), and posthog.capture(send_feature_flags=True)still work during the migration period, but they're deprecated. Preferposthog.evaluate_flags()` for new code.
Step 2: Include feature flag information when capturing events
If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API.
There are two methods you can use to include feature flag information in your events:
Method 1: Pass the evaluated flags snapshot to capture()
Pass the same flags object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another /flags request.
flags = posthog.evaluate_flags("distinct_id_of_your_user")
if flags.is_enabled("flag-key"):
# Do something differently for this user
pass
posthog.capture(
"event_name",
distinct_id="distinct_id_of_your_user",
flags=flags,
)
By default, this attaches every flag in the snapshot using $feature/<flag-key> properties and $active_feature_flags.
To reduce event property bloat, pass a filtered snapshot:
# Attach only flags accessed with is_enabled() or get_flag() before this call
posthog.capture(
"event_name",
distinct_id="distinct_id_of_your_user",
flags=flags.only_accessed(),
)
# Attach only specific flags
posthog.capture(
"event_name",
distinct_id="distinct_id_of_your_user",
flags=flags.only(["checkout-flow", "new-dashboard"]),
)
only_accessed() is order-dependent. If you call it before accessing any flags with is_enabled() or get_flag(), no feature flag properties are attached.
Method 2: Include the $feature/feature_flag_name property manually
In the event properties, include $feature/feature_flag_name: variant_key:
posthog.capture(
"event_name",
distinct_id="distinct_id_of_the_user",
properties={
# Replace feature-flag-key with your flag key and "variant-key" with the key of your variant
"$feature/feature-flag-key": "variant-key",
},
)
Evaluating only specific flags
By default, posthog.evaluate_flags() evaluates every flag for the user. If you only need a few flags, pass flag_keys to request only those flags:
flags = posthog.evaluate_flags(
"distinct_id_of_your_user",
flag_keys=["checkout-flow", "new-dashboard"],
)
Sending $feature_flag_called events
Capturing $feature_flag_called events enables PostHog to know when a flag was accessed by a user and provide analytics and insights on the flag. With posthog.evaluate_flags(), the SDK sends this event when you call flags.is_enabled() or flags.get_flag() for a flag.
The SDK deduplicates these events per (distinct_id, flag, value) in a local cache. If you reinitialize the PostHog client, the cache resets and $feature_flag_called events may be sent again. PostHog handles duplicates, so duplicate $feature_flag_called events don't affect your analytics.
flags.get_flag_payload() doesn't send $feature_flag_called events and doesn't count as an access for only_accessed().
Advanced: Overriding server properties
Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
flags = posthog.evaluate_flags(
"distinct_id_of_the_user",
person_properties={"property_name": "value"},
groups={
"your_group_type": "your_group_id",
"another_group_type": "your_group_id",
},
group_properties={
"your_group_type": {"group_property_name": "value"},
"another_group_type": {"group_property_name": "value"},
},
)
if flags.is_enabled("flag-key"):
# Do something differently for this user
Overriding GeoIP properties
By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location.
The following GeoIP properties can be overridden:
$geoip_country_code$geoip_country_name$geoip_city_name$geoip_city_confidence$geoip_continent_code$geoip_continent_name$geoip_latitude$geoip_longitude$geoip_postal_code$geoip_subdivision_1_code$geoip_subdivision_1_name$geoip_subdivision_2_code$geoip_subdivision_2_name$geoip_subdivision_3_code$geoip_subdivision_3_name$geoip_time_zone
Simply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.
Request timeout
You can configure the feature_flags_request_timeout_seconds parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog's servers are too slow to respond. By default, this is set to 3 seconds.
posthog = Posthog(
"<ph_project_token>",
host="https://us.i.posthog.com",
feature_flags_request_timeout_seconds=3, # Time in seconds. Defaults to 3.
)
PHP
There are two steps to implement feature flags in PHP:
Step 1: Evaluate flags once
Call PostHog::evaluateFlags() once for the user, then read values from the returned snapshot.
Boolean feature flags
$flags = PostHog::evaluateFlags('distinct_id_of_your_user');
if ($flags->isEnabled('flag-key')) {
// Do something differently for this user
// Optional: fetch the payload
$matchedFlagPayload = $flags->getFlagPayload('flag-key');
}
Multivariate feature flags
$flags = PostHog::evaluateFlags('distinct_id_of_your_user');
$enabledVariant = $flags->getFlag('flag-key');
if ($enabledVariant === 'variant-key') { // replace 'variant-key' with the key of your variant
// Do something differently for this user
// Optional: fetch the payload
$matchedFlagPayload = $flags->getFlagPayload('flag-key');
}
$flags->getFlag() returns the variant string for multivariate flags, true for enabled boolean flags, false for disabled flags, and null when the flag wasn't returned by the evaluation.
You can also call $flags->getKeys() to list the evaluated flag keys, or $flags->getEventProperties() to get the $feature/<flag-key> and $active_feature_flags properties that would be attached to a captured event.
Note:
PostHog::isFeatureEnabled(),PostHog::getFeatureFlag(),PostHog::getFeatureFlagPayload(), andcapture(['send_feature_flags' => true])still work during the migration period, but they're deprecated. PreferevaluateFlags()for new code.
Step 2: Include feature flag information when capturing events
If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API.
There are two methods you can use to include feature flag information in your events:
Method 1: Pass the evaluated flags snapshot to capture()
Pass the same flags object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another /flags request.
$flags = PostHog::evaluateFlags('distinct_id_of_your_user');
if ($flags->isEnabled('flag-key')) {
// Do something differently for this user
}
PostHog::capture([
'distinctId' => 'distinct_id_of_your_user',
'event' => 'event_name',
'flags' => $flags,
]);
By default, this attaches every flag in the snapshot using $feature/<flag-key> properties and $active_feature_flags.
To reduce event property bloat, pass a filtered snapshot:
// Attach only flags accessed with isEnabled() or getFlag() before this call
PostHog::capture([
'distinctId' => 'distinct_id_of_your_user',
'event' => 'event_name',
'flags' => $flags->onlyAccessed(),
]);
// Attach only specific flags
PostHog::capture([
'distinctId' => 'distinct_id_of_your_user',
'event' => 'event_name',
'flags' => $flags->only(['checkout-flow', 'new-dashboard']),
]);
onlyAccessed() is order-dependent. If you call it before accessing any flags with isEnabled() or getFlag(), no feature flag properties are attached.
Method 2: Include the $feature/feature_flag_name property manually
In the event properties, include $feature/feature_flag_name: variant_key:
PostHog::capture([
'distinctId' => 'distinct_id_of_your_user',
'event' => 'event_name',
'properties' => [
// Replace feature-flag-key with your flag key and 'variant-key' with the key of your variant
'$feature/feature-flag-key' => 'variant-key',
],
]);
Evaluating only specific flags
By default, evaluateFlags() evaluates every flag for the user. If you only need a few flags, pass flagKeys to request only those flags:
$flags = PostHog::evaluateFlags(
distinctId: 'distinct_id_of_your_user',
flagKeys: ['checkout-flow', 'new-dashboard'],
);
Optional evaluation parameters
evaluateFlags() also accepts optional parameters for local evaluation and GeoIP behavior:
$flags = PostHog::evaluateFlags(
distinctId: 'distinct_id_of_your_user',
groups: ['company' => 'company_id_in_your_db'],
personProperties: ['plan' => 'pro'],
groupProperties: ['company' => ['employees' => 11]],
onlyEvaluateLocally: false, // Defaults to false. Set to true to avoid a remote fallback.
disableGeoip: false, // Defaults to false. Set to true to disable GeoIP enrichment during remote evaluation.
flagKeys: ['checkout-flow', 'new-dashboard'],
);
Sending $feature_flag_called events
Capturing $feature_flag_called events enables PostHog to know when a flag was accessed by a user and provide analytics and insights on the flag. With evaluateFlags(), the SDK sends this event when you call $flags->isEnabled() or $flags->getFlag() for a flag.
The SDK deduplicates these events per (flag key, distinct_id) in a local cache. If you reinitialize the PostHog client, the cache resets and $feature_flag_called events may be sent again. PostHog handles duplicates, so duplicate $feature_flag_called events don't affect your analytics.
$flags->getFlagPayload() doesn't send $feature_flag_called events and doesn't count as an access for onlyAccessed().
Advanced: Overriding server properties
Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
$flags = PostHog::evaluateFlags(
distinctId: 'distinct_id_of_the_user',
groups: [
'your_group_type' => 'your_group_id',
'another_group_type' => 'your_group_id',
],
personProperties: ['property_name' => 'value'],
groupProperties: [
'your_group_type' => ['group_property_name' => 'value'],
'another_group_type' => ['group_property_name' => 'value'],
],
);
if ($flags->isEnabled('flag-key')) {
// Do something differently for this user
}
Overriding GeoIP properties
By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location.
The following GeoIP properties can be overridden:
$geoip_country_code$geoip_country_name$geoip_city_name$geoip_city_confidence$geoip_continent_code$geoip_continent_name$geoip_latitude$geoip_longitude$geoip_postal_code$geoip_subdivision_1_code$geoip_subdivision_1_name$geoip_subdivision_2_code$geoip_subdivision_2_name$geoip_subdivision_3_code$geoip_subdivision_3_name$geoip_time_zone
Simply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.
Request timeout
You can configure the feature_flag_request_timeout_ms parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog's servers are too slow to respond. By default, this is set to 3 seconds.
PostHog::init("<ph_project_token>",
[
'host' => 'https://us.i.posthog.com',
'feature_flag_request_timeout_ms' => 3000, // Time in milliseconds. Defaults to 3000 (3 seconds).
]
);
Ruby
There are two steps to implement feature flags in Ruby:
Step 1: Evaluate flags once
Call posthog.evaluate_flags() once for the user, then read values from the returned snapshot.
Boolean feature flags
flags = posthog.evaluate_flags('distinct_id_of_your_user')
if flags.enabled?('flag-key')
# Do something differently for this user
# Optional: fetch the payload
matched_flag_payload = flags.get_flag_payload('flag-key')
end
Multivariate feature flags
flags = posthog.evaluate_flags('distinct_id_of_your_user')
enabled_variant = flags.get_flag('flag-key')
if enabled_variant == 'variant-key' # replace 'variant-key' with the key of your variant
# Do something differently for this user
# Optional: fetch the payload
matched_flag_payload = flags.get_flag_payload('flag-key')
end
flags.get_flag() returns the variant string for multivariate flags, true for enabled boolean flags, false for disabled flags, and nil when the flag wasn't returned by the evaluation.
Note:
posthog.is_feature_enabled(),posthog.get_feature_flag(),posthog.get_feature_flag_result(),posthog.get_feature_flag_payload(), andcapture({ ..., send_feature_flags: true })still work during the migration period, but they're deprecated. Preferevaluate_flags()for new code.
Step 2: Include feature flag information when capturing events
If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API.
There are two methods you can use to include feature flag information in your events:
Method 1: Pass the evaluated flags snapshot to capture()
Pass the same flags object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another /flags request.
flags = posthog.evaluate_flags('distinct_id_of_your_user')
if flags.enabled?('flag-key')
# Do something differently for this user
end
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
flags: flags,
})
By default, this attaches every flag in the snapshot using $feature/<flag-key> properties and $active_feature_flags.
To reduce event property bloat, pass a filtered snapshot:
# Attach only flags accessed with enabled?() or get_flag() before this call
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
flags: flags.only_accessed,
})
# Attach only specific flags
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
flags: flags.only(['checkout-flow', 'new-dashboard']),
})
only_accessed is order-dependent. If you call it before accessing any flags with enabled?() or get_flag(), no feature flag properties are attached.
Method 2: Include the $feature/feature_flag_name property manually
In the event properties, include $feature/feature_flag_name: variant_key:
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
properties: {
# Replace feature-flag-key with your flag key and 'variant-key' with the key of your variant
'$feature/feature-flag-key': 'variant-key',
},
})
Evaluating only specific flags
By default, evaluate_flags() evaluates every flag for the user. If you only need a few flags, pass flag_keys to request only those flags:
flags = posthog.evaluate_flags(
'distinct_id_of_your_user',
flag_keys: ['checkout-flow', 'new-dashboard'],
)
Evaluating locally only
If you want to skip the remote /flags request and only use locally cached definitions, pass only_evaluate_locally: true:
flags = posthog.evaluate_flags(
'distinct_id_of_your_user',
only_evaluate_locally: true,
)
Disabling GeoIP for flag evaluation
Pass disable_geoip: true to disable GeoIP lookup for remote flag evaluation:
flags = posthog.evaluate_flags(
'distinct_id_of_your_user',
disable_geoip: true,
)
Sending $feature_flag_called events
Capturing $feature_flag_called events enables PostHog to know when a flag was accessed by a user and provide analytics and insights on the flag. With evaluate_flags(), the SDK sends this event when you call flags.enabled?() or flags.get_flag() for a flag.
The SDK deduplicates these events per (distinct_id, flag, value) in a local cache. If you reinitialize the PostHog client, the cache resets and $feature_flag_called events may be sent again. PostHog handles duplicates, so duplicate $feature_flag_called events don't affect your analytics.
flags.get_flag_payload() doesn't send $feature_flag_called events and doesn't count as an access for only_accessed.
Advanced: Overriding server properties
Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
flags = posthog.evaluate_flags(
'distinct_id_of_the_user',
person_properties: {
property_name: 'value'
},
groups: {
your_group_type: 'your_group_id',
another_group_type: 'your_group_id',
},
group_properties: {
your_group_type: {
group_property_name: 'value'
},
another_group_type: {
group_property_name: 'value'
},
},
)
if flags.enabled?('flag-key')
# Do something differently for this user
end
Overriding GeoIP properties
By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location.
The following GeoIP properties can be overridden:
$geoip_country_code$geoip_country_name$geoip_city_name$geoip_city_confidence$geoip_continent_code$geoip_continent_name$geoip_latitude$geoip_longitude$geoip_postal_code$geoip_subdivision_1_code$geoip_subdivision_1_name$geoip_subdivision_2_code$geoip_subdivision_2_name$geoip_subdivision_3_code$geoip_subdivision_3_name$geoip_time_zone
Simply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.
Request timeout
You can configure the feature_flag_request_timeout_seconds parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog's servers are too slow to respond. By default, this is set to 3 seconds.
posthog = PostHog::Client.new({
# rest of your configuration...
feature_flag_request_timeout_seconds: 3 # Time in seconds. Defaults to 3.
})
Go
There are two steps to implement feature flags in Go:
Step 1: Evaluate flags once
Call client.EvaluateFlags() once for the user, then read values from the returned snapshot.
Boolean feature flags
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_your_user",
})
if err != nil {
// Handle error (e.g. capture error and fallback to default behavior)
}
if flags.IsEnabled("flag-key") {
// Do something differently for this user
// Optional: fetch the payload
matchedFlagPayload := flags.GetFlagPayload("flag-key")
}
Multivariate feature flags
flags, err := client.EvaluateFlags(posthog.EvaluateFlagsPayload{
DistinctId: "distinct_id_of_your_user",
})
if err != nil {
// Handle error (e.g. capture error and fallback to default behavior)
}
enabledVariant := flags.GetFlag("flag-key")
if enabledVariant == "variant-key" { // replace "variant-key" with the key of your variant
// Do something differently for this user
// Optional: fetch the payload
matchedFlagPayload := flags.GetFlagPayload("flag-key")
}
flags.GetFlag() returns the variant string for multivariate flags, true for enabled boolean flags, false for disabled flags, and nil when the flag wasn't re