PHP

This is an optional library you can install if you're working with PHP. It uses an internal queue to batch requests, flushes at the end of the request, and optionally does so in an async manner.

Installation

Add the following to composer.json:

JSON
{
    "require": {
        "posthog/posthog-php": "3.0.*"
    }
}

And then install the dependencies with the command:

Terminal
composer install

In your app, set your project token before making any calls.

PHP
PostHog\PostHog::init("<ph_project_token>",
  ['host' => 'https://us.i.posthog.com'] 
);

Note: As a rule of thumb, we do not recommend having API keys or tokens in plaintext. Setting it as an environment variable is best.

You can find your project token and instance address in the project settings page in PostHog.

Identifying users

Identifying users is required. Backend events need a distinct_id that matches the ID your frontend uses when calling posthog.identify(). Without this, backend events are orphaned — they can't be linked to frontend event captures, session replays, LLM traces, or error tracking.
See our guide on identifying users for how to set this up.

Capturing events

You can send custom events using capture:

PHP
PostHog::capture([
  'distinctId' => 'distinct_id_of_the_user',
  'event' => 'user_signed_up'
]);

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can include additional information with the event by including a properties object:

PHP
PostHog::capture([
  'distinctId' => 'distinct_id_of_the_user',
  'event' => 'user_signed_up',
  'properties' => [
    'login_type' => 'email',
    'is_free_trial' => 'true'
  ]
]);

Sending page views

If you're aiming for a backend-only implementation of PostHog and won't be capturing events from your frontend, you can send pageviews from your backend like so:

PHP
PostHog::capture([
  'distinctId' => 'distinct_id_of_the_user',
  'event' => '$pageview',
  'properties' => [
    '$current_url' => 'https://example.com'
  ]
]);

Person profiles and properties

The PHP SDK captures identified events by default. These create person profiles. To set person properties in these profiles, include them when capturing an event:

PHP
PostHog::capture([
    'distinctId' => 'distinct_id',
    'event' => 'event_name',
    'properties' => [
        '$set' => [
            'name' => 'Max Hedgehog'
        ],
        '$set_once' => [
            'initial_url' => '/blog'
        ]
    ]
]);

For more details on the difference between $set and $set_once, see our person properties docs.

To capture anonymous events without person profiles, set the event's $process_person_profile property to false:

PHP
PostHog::capture([
    'distinctId' => 'distinct_id',
    'event' => 'event_name',
    'properties' => [
        '$process_person_profile' => false
    ]
]);

Alias

Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.

In this case, you can use alias to assign another distinct ID to the same user.

PHP
PostHog::alias([
  'distinctId' => 'distinct_id',
  'alias' => 'alias_id'
]);

We strongly recommend reading our docs on alias to best understand how to correctly use this method.

Feature flags

PostHog's feature flags enable you to safely deploy and roll back new features as well as target specific users and groups with them.

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

PHP
$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

PHP
$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.

Note: PostHog::isFeatureEnabled(), PostHog::getFeatureFlag(), PostHog::getFeatureFlagPayload(), and capture(['send_feature_flags' => true]) still work during the migration period, but they're deprecated. Prefer evaluateFlags() 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.

PHP
$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:

PHP
// 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:

PHP
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:

PHP
$flags = PostHog::evaluateFlags(
    distinctId: 'distinct_id_of_your_user',
    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 (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->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:

PHP
$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.

PHP
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).
    ]
);

Local Evaluation

Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.

It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.

For details on how to implement local evaluation, see our local evaluation guide.

Experiments (A/B tests)

Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code:

PHP
$flags = PostHog::evaluateFlags('user_distinct_id');
$variant = $flags->getFlag('experiment-feature-flag-key');

if ($variant === 'variant-name') {
    // Do something differently for this user
}

It's also possible to run experiments without using feature flags.

Group analytics

Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). This feature requires a posthog-php version of 2.1.0 or above. Read the Group Analytics guide for more information.

Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more on the pricing page.

Capture an event and associate it with a group

PHP
PostHog::capture([
    'distinctId' => 'user_distinct_id',
    'event' => 'some_event',
    '$groups' => ['company' => 'company_id_in_your_db']
]);

Update properties on a group

PHP
PostHog::groupIdentify([
    'groupType' => 'company',
    'groupKey' => 'company_id_in_your_db',
    'properties' => ['name' => 'Awesome Inc.', 'employees' => 11]
]);

The name is a special property which is used in the PostHog UI for the name of the group. If you don't specify a name property, the group ID will be used instead.

Error tracking

The PHP SDK supports both manual exception capture and opt-in automatic error tracking.

To automatically capture uncaught exceptions, PHP errors, and fatal shutdown errors, enable error_tracking when initializing the client:

PHP
PostHog::init(
    '<ph_project_token>',
    [
        'host' => 'https://us.i.posthog.com',
        'error_tracking' => [
            'enabled' => true,
        ],
    ],
);

You can also call PostHog::captureException() directly for manual capture. When source files are readable at runtime, PostHog includes surrounding source lines for in-app stack frames automatically.

For the full setup guide, including context_provider, excluded exceptions, and verification steps, see the PHP error tracking installation docs.

Config options

When calling PostHog::init, there are various configuration options you can set apart from the host. Pass them into your client initialisation like so:

PHP
PostHog::init(
    '<ph_project_token>',
    [
        'host' => 'https://us.i.posthog.com', 
        'debug' => true,
        'ssl' => false,
        // all options go here
    ],
);

All possible options below:

Attribute	Description
`host` Type: String Default: `app.posthog.com`	URL of your PostHog instance.
`ssl` Type: Boolean Default: `true`	Whether to use SSL for API requests or not
`timeout` Type: Integer Default: `10000`	Request timeout in milliseconds
`verify_batch_events_request` Type: Boolean Default: `true`	Whether to verify successful delivery of batch events (true, synchronous) or fire and forget (false, asynchronous) with the `lib_curl` consumer
`feature_flag_request_timeout_ms` Type: Integer Default: `3000`	Request timeout for feature flags in milliseconds
`maximum_backoff_duration` Type: Integer Default: `10000`	Request retry backoff. Retries will stop after this duration is hit
`consumer` Type: String Default: `lib_curl`	One of `socket`, `file`, `lib_curl`, and `fork_curl`. Determines what transport option to use for analytics capture. More details here
`debug` Type: Boolean Default: `false`	Output debug logs or not
`error_tracking` Type: Array Default: `[]`	Enables automatic error tracking and related options such as `context_provider`, `excluded_exceptions`, and `max_frames`. See the setup guide.

Debug mode

PHP
PostHog::init(
    '<ph_project_token>',
    [
        'host' => 'https://us.i.posthog.com', 
        'debug' => true, 
    ],
);

Thank you

This library is largely based on the analytics-php package.

PHP

Contents

Installation

Identifying users

Capturing events

Setting event properties

Sending page views

Person profiles and properties

Alias

Feature flags

Step 1: Evaluate flags once

Boolean feature flags

Multivariate feature flags

Step 2: Include feature flag information when capturing events

Method 1: Pass the evaluated flags snapshot to `capture()`

Method 2: Include the `$feature/feature_flag_name` property manually

Evaluating only specific flags

Sending `$feature_flag_called` events

Advanced: Overriding server properties

Overriding GeoIP properties

Request timeout

Local Evaluation

Experiments (A/B tests)

Group analytics

Error tracking

Config options

Debug mode

Thank you

Community questions

Was this page useful?

PHP

Contents

Installation

Identifying users

Capturing events

Setting event properties

Sending page views

Person profiles and properties

Alias

Feature flags

Step 1: Evaluate flags once

Boolean feature flags

Multivariate feature flags

Step 2: Include feature flag information when capturing events

Method 1: Pass the evaluated flags snapshot to capture()

Method 2: Include the $feature/feature_flag_name property manually

Evaluating only specific flags

Sending $feature_flag_called events

Advanced: Overriding server properties

Overriding GeoIP properties

Request timeout

Local Evaluation

Experiments (A/B tests)

Group analytics

Error tracking

Config options

Debug mode

Thank you

Community questions

Was this page useful?

Method 1: Pass the evaluated flags snapshot to `capture()`

Method 2: Include the `$feature/feature_flag_name` property manually

Sending `$feature_flag_called` events