PHP

This is an optional library you can install if you're working with PHP. It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server-side application that needs performance.

Installation

Add the following to composer.json:

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

And then install the dependencies with the command:

php composer.phar install

In your app, set your project API key before making any calls.

PostHog::init("<ph_project_api_key>",
  array('host' => '<ph_instance_address>') 
);

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

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

Capturing events

You can send custom events using capture:

PostHog::capture(array(
  '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 also include additional information in the event by setting the properties value:

PostHog::capture(array(
  'distinctId' => 'distinct_id_of_the_user',
  'event' => 'user signed up',
  'properties' => array(
    '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:

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

Setting user properties

To set user properties, include the properties you'd like to set when capturing an event:

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

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

Alias

Sometimes, you may want to assign multiple distinct IDs to a single user. This is helpful in scenarios where your primary distinct ID may be inaccessible. For example, if a distinct ID which is typically used on the frontend is not available in certain parts of your backend code. In this case, you can use alias to assign another distinct ID to the same user.

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.

There are 2 steps to implement feature flags in PHP:

Step 1: Evaluate the feature flag value

Boolean feature flags

$isMyFlagEnabledForUser = PostHog::isFeatureEnabled('flag-key', 'distinct_id_of_your_user')

if ($isMyFlagEnabledForUser) {
    // Do something differently for this user
}

Multivariate feature flags

$enabledVariant = PostHog::getFeatureFlag('flag-key', 'distinct_id_of_your_user')

if ($enabledVariant === 'variant-key') { # replace 'variant-key' with the key of your variant
    # Do something differently for this user
}

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: Include the $feature/feature_flag_name property

In the event properties, include $feature/feature_flag_name: variant_key:

PostHog::capture(array(
  'distinctId' => 'distinct_id_of_your_user',
  'event' => 'event_name',
  'properties' => array(
    '$feature/feature-flag-key'  = 'variant-key' # replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
  )
));

Method 2: Set sendFeatureFlagEvents to true

The capture() method has an optional argument sendFeatureFlagEvents, which is set to false by default. By setting this to true, feature flag information will automatically be sent with the event.

Note that by doing this, PostHog will make an additional request to fetch feature flag information before capturing the event. So this method is only recommended if you don't mind the extra API call and delay.

PostHog::capture(array(
  'distinctId' => 'distinct_id_of_your_user',
  'event' => 'event_name',
  'sendFeatureFlagEvents' => true
));

Fetching all flags for a user

You can fetch all flag values for a single user by calling getAllFlags().

This is useful when you need to fetch multiple flag values and don't want to make multiple requests.

PostHog::getAllFlags('distinct_id_of_your_user')

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:

PostHog::getFeatureFlag(
    'flag-key',
    'distinct_id_of_the_user',
    [
        'your_group_type' => 'your_group_id',
        'another_group_type' => 'your_group_id'
    ], // groups
    ['property_name' => 'value'], // person properties
    [
        'your_group_type' => ['group_property_name' => 'value'], 
        'another_group_type' => ['group_property_name' => 'value']
    ], // group properties
    false, // onlyEvaluateLocally, Optional. Defaults to false.
    true // sendFeatureFlagEvents
);

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:

$variant = PostHog::getFeatureFlag('experiment-feature-flag-key', 'user_distinct_id')

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 here.

• Capture an event and associate it with a group

PostHog::capture(array(
    'distinctId' => '[user distinct id]',
    'event' => 'some event',
    '$groups' => array("company" => "company_id_in_your_db")
));

• Update properties on a group

PostHog::groupIdentify(array(
    'groupType' => 'company',
    'groupKey' => 'company_id_in_your_db',
    'properties' => array("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.

Thank you

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