> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt # PHP Canonical URL: https://posthog.com/docs/libraries/php > **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.i.posthog.com` instead of `https://us.i.posthog.com` (ingestion host), and use `https://eu.posthog.com` instead of `https://app.posthog.com` (app host for links). ## On this page - [Installation](#installation) - [Identifying users](#identifying-users) - [Capturing events](#capturing-events) - [Person profiles and properties](#person-profiles-and-properties) - [Alias](#alias) - [Feature flags](#feature-flags) - [Request context](#request-context) - [Error tracking](#error-tracking) - [Config options](#config-options) - [Flushing and shutting down](#flushing-and-shutting-down) - [Debug mode](#debug-mode) - [Thank you](#thank-you) 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. Using Laravel? See our [Laravel guide](https://posthog.com/docs/libraries/laravel.md) for the experimental Laravel SDK or [manual integration with the PHP SDK](https://posthog.com/docs/libraries/laravel.md#manual-setup-with-the-php-sdk). Using the PHP SDK directly with your own instrumentation remains supported. ## Installation Install the package with Composer: ```bash composer require "posthog/posthog-php:^4.0" ``` In your app, set your project token before making any calls. ```php PostHog\PostHog::init("", ['host' => 'https://us.i.posthog.com'] ); ``` > **Note:** As a rule of thumb, we do not recommend having API keys or tokens in plaintext. Setting them as environment variables is best. The PHP SDK reads `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` when you omit the project token or host. If `POSTHOG_PROJECT_TOKEN` is not set, it reads `POSTHOG_API_KEY`. SDK versions before 4.23.0 read only `POSTHOG_API_KEY`. You can find your project token and instance address in the [project settings](https://app.posthog.com/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](https://posthog.com/docs/session-replay.md), [LLM traces](https://posthog.com/docs/ai-engineering.md), or [error tracking](https://posthog.com/docs/error-tracking.md). > > See our guide on [identifying users](https://posthog.com/docs/getting-started/identify-users.md) 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](https://posthog.com/docs/data/events.md#event-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](https://posthog.com/docs/data/persons.md). To set [person properties](https://posthog.com/docs/product-analytics/person-properties.md), call `identify` with the user's distinct ID and properties: ```php PostHog::identify([ 'distinctId' => 'distinct_id', 'properties' => [ 'email' => 'max@example.com', 'name' => 'Max Hedgehog', ], ]); ``` You can also include person properties 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](https://posthog.com/docs/product-analytics/person-properties.md#what-is-the-difference-between-set-and-set_once). To capture [anonymous events](https://posthog.com/docs/data/anonymous-vs-identified-events.md) 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](https://posthog.com/docs/product-analytics/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method. ## Feature flags PostHog's [feature flags](https://posthog.com/docs/feature-flags.md) 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. You can also call `$flags->getKeys()` to list the evaluated flag keys, or `$flags->getEventProperties()` to get the `$feature/` and `$active_feature_flags` properties that would be attached to a captured event. > **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](https://posthog.com/docs/product-analytics/insights.md), 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](https://posthog.com/docs/api.md). 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/` 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'], ); ``` ### Optional evaluation parameters `evaluateFlags()` also accepts optional parameters for local evaluation and GeoIP behavior: ```php $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](https://posthog.com/docs/product-analytics/insights.md) 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](https://posthog.com/docs/product-analytics/person-properties.md), [groups](https://posthog.com/docs/product-analytics/group-analytics.md), 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("", [ '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. To load feature flag definitions for local evaluation, initialize the SDK with your secret API key as `personalAPIKey`: ```php PostHog::init( '', ['host' => 'https://us.i.posthog.com'], personalAPIKey: 'your secret API key' ); ``` For details on how to implement local evaluation, see our [local evaluation guide](https://posthog.com/docs/feature-flags/local-evaluation.md). For distributed or stateless PHP applications, use `flag_definition_cache_provider` to share flag definitions across workers or requests. See [local evaluation in distributed environments](https://posthog.com/docs/feature-flags/local-evaluation/distributed-environments?tab=PHP.md). ### Experiments (A/B tests) Since [experiments](https://posthog.com/docs/experiments/start-here.md) 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](https://posthog.com/docs/experiments/running-experiments-without-feature-flags.md). ### Group analytics Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). This feature requires version `2.1.0` or above of the PHP SDK. Read the [group analytics guide](https://posthog.com/docs/product-analytics/group-analytics.md) 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](https://posthog.com/pricing.md). To create a group or update its properties, use `groupIdentify`: ```php PostHog::groupIdentify([ 'groupType' => 'company', 'groupKey' => 'company_id_in_your_db', 'properties' => [ 'name' => 'Awesome Inc.', 'employees' => 11, ], // Optional distinct ID to associate this event with an existing person. // Requires posthog-php 4.4.0 or later. 'distinctId' => 'user_distinct_id' ]); ``` `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 is used instead. If the optional `distinctId` parameter is not provided in the group identify call, it defaults to `${groupType}_${groupKey}` (e.g., `$company_company_id_in_your_db` in the example above). This default behavior results in each group appearing as a separate person in PostHog. To avoid this, use a consistent `distinctId`, such as `group_identifier`, or a real user distinct ID. Once a group is created, you can use the `capture` method and pass in the `groups` parameter to capture an event with group analytics. ```php PostHog::capture([ 'distinctId' => 'user_distinct_id', 'event' => 'some_event', 'groups' => ['company' => 'company_id_in_your_db'] ]); ``` ## Request context Use request context to apply a distinct ID, session ID, and common properties to all captures inside a callback. This is useful when connecting frontend activity to backend events, session replay, and error tracking. ```php PostHog::withContext([ 'distinctId' => 'user_distinct_id', 'sessionId' => 'session_id_from_frontend', 'properties' => [ '$current_url' => 'https://example.com/account', ], ], function () { PostHog::capture([ 'event' => 'backend_event', ]); }); ``` You can extract PostHog context from frontend tracing headers with `contextFromHeaders()`. If you're using [PostHog JS](https://posthog.com/docs/libraries/js.md) on the frontend, configure [`tracing_headers`](https://posthog.com/docs/libraries/js/config.md#tracing-headers) for your PHP backend hostname so browser requests include the session and distinct ID headers. Then read the incoming headers on the server: ```php $context = PostHog::contextFromHeaders($_SERVER); PostHog::withContext($context, function () { PostHog::capture([ 'event' => 'backend_event', ]); }); ``` Call `PostHog::getContext()` to read the currently active context. Pass `['fresh' => true]` as the third argument to `withContext()` if you don't want to inherit any existing context. Tracing headers are client-controlled analytics context, not authentication or authorization. Pass an authenticated `distinctId` explicitly for security-sensitive server-side decisions. ## 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( '', [ '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](https://posthog.com/docs/error-tracking/installation/php.md). ## 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( '', [ 'host' => 'https://us.i.posthog.com', 'debug' => true, 'ssl' => false, // all options go here ], ); ``` All possible options below: | Attribute | Description | | --- | --- | | `host` **Type:** String **Default:** `us.i.posthog.com` | URL of your PostHog instance. | | `ssl` **Type:** Boolean **Default:** `true` | Whether to use SSL for API requests or not. If `host` includes `http://` or `https://`, the SDK infers this option unless you set it explicitly. | | `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. | | `flag_definition_cache_provider` **Type:** `PostHog\FlagDefinitionCacheProvider` **Default:** `null` | Provider for distributed local-evaluation flag definition caching. See [local evaluation in distributed environments](https://posthog.com/docs/feature-flags/local-evaluation/distributed-environments?tab=PHP.md). | | `maximum_backoff_duration` **Type:** Integer **Default:** `10000` | Request retry backoff. Retries stop after this duration is hit. | | `consumer` **Type:** String **Default:** `lib_curl` | One of `socket`, `file`, `lib_curl`, `fork_curl`, and `noop`. Determines what transport option to use for analytics capture. | | `debug` **Type:** Boolean **Default:** `false` | Output debug logs or not. | | `max_queue_size` **Type:** Integer **Default:** `1000` | Maximum number of events to queue before rejecting new events. Applies to queued consumers. | | `batch_size` **Type:** Integer **Default:** `100` | Number of queued events to send in each batch. Applies to queued consumers. | | `compress_request` **Type:** Boolean/String **Default:** `false` | Whether to gzip batch request payloads. | | `error_handler` **Type:** Callable **Default:** `null` | Callback invoked for SDK transport errors. | | `filename` **Type:** String **Default:** `sys_get_temp_dir() . '/posthog.log'` | File path used when `consumer` is set to `file`. | | `error_tracking` **Type:** Array **Default:** `[]` | Enables automatic error tracking. See the options below or the [PHP error tracking setup guide](https://posthog.com/docs/error-tracking/installation/php.md). | ### Error tracking options | Attribute | Description | | --- | --- | | `enabled` **Type:** Boolean **Default:** `false` | Enables automatic error tracking handlers. Manual `captureException` works regardless. | | `capture_errors` **Type:** Boolean **Default:** `true` | When enabled, captures PHP errors and fatal shutdown errors in addition to uncaught exceptions. | | `excluded_exceptions` **Type:** Array of class strings **Default:** `[]` | Throwable classes to skip during automatic capture. | | `max_frames` **Type:** Integer **Default:** `20` | Maximum number of stack frames included in `$exception_list`. | | `context_provider` **Type:** Callable or `null` **Default:** `null` | Callback that returns `distinctId` and extra event properties for automatic captures. | ## Flushing and shutting down Call `PostHog::flush()` to send queued events without closing resources. When a script or long-running worker stops, call `PostHog::shutdown()` instead; it flushes queued events and releases resources held by providers such as `flag_definition_cache_provider`. ```php PostHog::shutdown(); ``` ## Debug mode ```php PostHog::init( '', [ 'host' => 'https://us.i.posthog.com', 'debug' => true, ], ); ``` ## Thank you This library is largely based on the `analytics-php` package.