NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #764 most downloaded on Packagist
PostHog PHP Library
Latest stable
4.23.0
Last release 12 days ago
10 Nov 2026
Ships on a steady schedule
a new release about every 1 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
105 releases · first in 2021
Drag across the ruler to compare, or tap a release to open it.
POSTHOG_API_KEY still works as a fallback, and the Laravel config gains a project_token key. The api_key key is deprecated and still read when project…
POSTHOG_PROJECT_TOKEN. POSTHOG_API_KEY still works as a fallback, and the Laravel config gains a project_token key. The api_key key is deprecated and still read when project_token is blank.Suppress definition-load warnings for client-only flags. Preserve PHP's fresh-response-only warning policy to avoid per-request log spam from shared-c
Your coding agent can read these notes before it upgrades. Set up the MCP server →
The new emails() sends transactional email from your PHP code and reads each email's delivery status.
The new emails() sends transactional email from your PHP code and reads each email's delivery status.
PostHog::init('phc_...', ['host' => 'https://us.i.posthog.com'], secretKey: 'phs_...');
$result = PostHog::emails()->send([
'to' => 'user@example.com',
'distinct_id' => 'user_123',
'template_key' => 'password-reset',
'subject' => 'Reset your password',
'html' => $renderedHtml,
]);
// 'delivered', 'bounced', ...
$status = PostHog::emails()->get($result->getId())->getStatus();
You can also send a template made in PostHog by its template_id.
You need a project secret API key, the kind that starts with phs_. Create one under Project secret API keys in your project settings. Set its Transactional email scope to Write to send emails, or to Read for a key that only reads statuses. Pass it to the client as secretKey. Set the app_host option to your PostHog app URL when you self-host PostHog or send through a reverse proxy. The client also loads feature flags with this key when it starts, so give it Feature flags: Read too, or it logs an error each time a client starts.
PostHog records each email's delivery, opens and clicks on the person with that distinct_id. It groups every email with the same template_key, so you see their metrics and logs in one place. The SDK retries a request that hits a network error, a rate limit or an outage twice by default. Every send carries an idempotency key, so a retry never sends the email twice. Pass your own idempotency_key, such as welcome:user_123, and your job runner's retries are safe too.
A send with your own content also takes from, reply_to and 'capture_engagement' => false. Set the migrated_from option to tell PostHog which email provider you moved from. A failed call throws a PostHog\EmailError. Its getErrorCode() returns PostHog's code, and getStatusCode() returns the HTTP status.
Docs: Send transactional emails with PHP and the transactional email overview.
Separate socket delivery timeouts from SDK HTTP deadlines and add http_timeout_ms for explicit HTTP configuration.
## 4.20.2 ### Patch Changes - Test the release process
Fix URL-style hosts for feature flag evaluation and definition requests.
Add instance group identify, lifecycle context scopes, and framework exception metadata.
Report the flags local evaluation could not resolve on evaluateFlags() snapshots. FeatureFlagEvaluations::getUnresolvedFlags() maps each such flag key
Report the flags local evaluation could not resolve on evaluateFlags() snapshots. FeatureFlagEvaluations::getUnresolvedFlags() maps each such flag key to an UnresolvedFlagReason value: experience_continuity, unsupported_definition, unresolved_dependency or missing_context.
Behavior changes:
false locally instead of going to the server.onlyEvaluateLocally.$feature_flag_called events from snapshot reads of unresolved flags report local_evaluation_inconclusive instead of flag_missing.debug off, that names the flags local evaluation can never resolve: flags with experience continuity, and flags that use a static cohort, an unknown operator, a malformed value, or a missing or circular dependency. Each flag is warned about once per client until its definition changes. Definitions from a cache provider or a 304 response do not log the warning. Without a flag_definition_cache_provider, each new client fetches fresh definitions, so under PHP-FPM the warning is logged on every request. Configure a cache provider to log it only when definitions are fetched.Retry transient HTTP responses and honor Retry-After in Socket and foreground ForkCurl consumers. Redirects and other unexpected responses count as tr
Retry transient HTTP responses and honor Retry-After in Socket and foreground ForkCurl consumers. Redirects and other unexpected responses count as transient; only 4xx client errors other than 408 and 429 drop the batch. When retries run out on a retryable response, all HTTP consumers now keep the batch queued instead of dropping it, and automatic flushes wait for the maximum backoff duration before they try again. A queue that fills during that wait flushes again once the wait ends.
Stop the Socket consumer from resending a batch forever when the server answers with a redirect. Socket now retries redirects and other unexpected responses with backoff, and stops at the backoff limit.
Normalize NaN and infinity to null in bounded data-only JSON payloads, while preserving native encoding for objects, references and out-of-budget payl
Add an optional OpenTelemetry context processor for session and person IDs on application spans.
Keep local regex evaluation compatible with the flags service by using strict end anchors and falling back for unsupported regex syntax.
Honor experiment holdouts when evaluating feature flags locally, so a held-out identifier resolves to holdout- instead of an ordinary variant.
holdout-<id> instead of an ordinary variant.Fix socket retries failing after reconnecting or crashing when reconnection fails.
Fix socket retries failing after reconnecting or crashing when reconnection fails.
Contain application failures during automatic SDK destruction without suppressing explicit shutdown retry exceptions, and finish cleanup after flush failures.
Honor configured ingestion timeouts in the libcurl and forked curl transports, rounding positive fractional milliseconds up so they remain bounded.
Cap Retry-After delays at maximum_backoff_duration to bound synchronous retry waits.
Fix local feature flag gt, gte, lt, and lte comparisons to compare numeric strings numerically, which can change flag membership for numeric-string pr
gt, gte, lt, and lte comparisons to compare numeric strings numerically, which can change flag membership for numeric-string properties. Invalid property values no longer compare lexicographically; invalid numeric filters fall back to remote evaluation.Add the active OpenTelemetry trace and span IDs to captured exception events when the application provides OpenTelemetry.
Add a client-wide disableGeoip option and per-call overrides for events and remote feature flag evaluation. Keep the default false for compatibility w
Match regex and not_regex flag filters locally the way the flags service does. The filter value is now always used as the pattern itself, so patterns
regex and not_regex flag filters locally the way the flags service does. The filter value is now always used as the pattern itself, so patterns containing / (such as ^https://example\.com/) or starting with a bracket (such as [abc]) no longer evaluate to false, and slash-wrapped values like /abc/i are matched literally. Property values are stringified like the other string operators (null, booleans, floats, and arrays included), so an array property no longer throws a TypeError out of getFeatureFlag. Patterns run in Unicode mode, and a regex execution failure is now inconclusive instead of silently making not_regex match.Allow shared flag definition cache providers to load and refresh local evaluation definitions without a secret key.
Keep session-attribution properties on minimized $feature_flag_called events. $referring_domain, utm_source, utm_medium, utm_campaign, utm_content, ut
$feature_flag_called events. $referring_domain, utm_source, utm_medium, utm_campaign, utm_content, utm_term, gad_source, mc_cid, and the click-id params posthog-js keeps (gclid, fbclid, msclkid, ttclid, and the rest) now survive the minimal-event allowlist, so a minimized event that happens to be a session's first event no longer nulls out that session's attribution in web analytics. Full $referrer stays excluded.Preserve escaped characters in gzip-compressed fork-curl event payloads.
Read the release id from the POSTHOG_RELEASE_ID environment variable and send it as $release_id on every event, including minimal $feature_flag_called
POSTHOG_RELEASE_ID environment variable and send it as $release_id on every event, including minimal $feature_flag_called events. On $exception events, error tracking uses it to link the exception to its release by a direct id lookup. Create the release and get its id with posthog-cli release resolve. An explicit $release_id in the event properties or in the request context wins over the environment variable. Under PHP-FPM, pass the variable through to workers (clear_env = no or an env[POSTHOG_RELEASE_ID] pool entry).Honor the definitions snapshot's property_matching_version during local feature flag evaluation, including group, cohort, and flag dependency conditio
property_matching_version during local feature flag evaluation, including group, cohort, and flag dependency conditions. Version 2 uses explicit boolean matching; missing or other versions retain legacy matching. Preserve the selector across external definition caches and reloads.Resolve feature flag payloads during local evaluation from the definition's filters.payloads, so evaluateFlags()->getFlagPayload() and getFeatureFlagP
filters.payloads, so evaluateFlags()->getFlagPayload() and getFeatureFlagPayload() no longer return null for locally evaluated flags.Match local feature flag boolean coercion, JSON stringification, numeric formatting, and string case handling with the flags service.
Return false for the is_not_set operator during local evaluation when the property key is present.
is_not_set operator during local evaluation when the property key is present.Return an empty feature flag snapshot without evaluation requests when the requested flag key list is empty.
Apply batch payload size checks consistently before transport processing
Normalize SDK timestamps to UTC before serialization.
Preserve fractional seconds and emit event timestamps in UTC.
Support the starts_with, not_starts_with, ends_with, and not_ends_with property filter operators in feature flag local evaluation. Matching is case-in
Support the starts_with, not_starts_with, ends_with, and not_ends_with property filter operators in feature flag local evaluation. Matching is case-insensitive and mirrors icontains. Previously, local evaluation treated these operators as unrecognized and silently evaluated their conditions to false; they now match correctly.
Operators local evaluation doesn't recognize now throw InconclusiveMatchException, deferring the flag to the /flags endpoint instead of producing a silently wrong false — so operators the server adds in the future degrade gracefully.
test: release with new changeset management
45c1b23: Send minimal $feature_flag_called events when the server enables the minimal_flag_called_events gate and the flag is not linked to an experim
a657369: Emit error tracking stack frames in the canonical bottom-up order: stacktrace.frames[0] is now the outermost/entry-point call and the last fr
stacktrace.frames[0] is now the outermost/entry-point call and the last frame is the crash site. This aligns the PHP SDK with the cross-SDK stack frame ordering standard.c6c637c: Add a $feature_flag_has_experiment boolean property to $feature_flag_called events, mirroring the server's has_experiment field. The property
fa53311: Add a before_send callback for modifying or dropping fully enriched events.
3ab7c80: Stop duplicating distinct_id inside /flags person properties.
distinct_id inside /flags person properties.6db62ec: Retry remote feature flag requests after transient 502 and 504 responses.
afa2dde: Harden the automated release workflow.
b1a5645: Retry capture delivery on transient HTTP errors and respect Retry-After responses.
8974819: Fall back to uncompressed batch uploads when local gzip compression fails.
2f594df: Retry feature flag requests after transient network errors only. The feature flag request retry count defaults to 1 and can be set to 0 to di
a6f28af: Dedupe feature flag called events by response value.
5ed7184: Validate top-level event UUIDs and replace invalid values with generated UUIDs.
21514df: Retain queued batches after network or timeout flush failures.
6e8b141: Copy capture groups input to the $groups event property so grouped events are associated correctly.
groups input to the $groups event property so grouped events are associated correctly.fac3a93: Add an external flag definition cache provider for sharing local-evaluation definitions across PHP SDK instances.
3ff0479: Add configurable flush interval support for queued event batching.
b7b6cf0: Stop sending deprecated, backend-ignored top-level batch event fields. SDK metadata now uses canonical event properties ($lib, $lib_version,…
$lib, $lib_version, $lib_consumer), while legacy top-level SDK metadata values remain supported as fallbacks when canonical values are absent. type is ignored, and send_feature_flags remains a deprecated capture option but is stripped from the outgoing /batch/ payload.4e0eb86: Support the early_exit flag filter in local evaluation. When a flag's filters.early_exit is true and a condition group's property filters mat
early_exit flag filter in local evaluation. When a flag's filters.early_exit is true and a condition group's property filters match (or there are none) but the rollout percentage excludes the user, evaluation now stops and returns false immediately instead of falling through to later groups. Mirrors the server-side (Rust) evaluation engine. A property-filter mismatch still falls through as before, and behaviour is unchanged when early_exit is unset or false.aa10180: Add a configurable $is_server event property (default true) so PostHog can identify server-side events. Set is_server to false when using pos
$is_server event property (default true) so PostHog can identify server-side events. Set is_server to false when using posthog-php as a client/CLI so the device OS is attributed normally.ccba73f: No-op facade and feature flag APIs when the SDK is uninitialized or non-operational.
e26230c: Move const inside class to prevent memory leaks in worker mode
806dd0b: Initialize a disabled no-op client instead of throwing or sending requests when the API key is missing or blank.
83afee8: Include group context in the $feature_flag_called dedupe element so group-scoped flags fire a separate event for each group a user is evaluat
$feature_flag_called dedupe element so group-scoped flags fire a separate event for each group a user is evaluated under, instead of being dedup-ed against the first group context the same (distinct_id, flag) was seen under.9adcdd6: Add request context helpers for propagating request metadata and optional PostHog tracing headers.
distinctId/distinct_id override for groupIdentify() events.## 4.3.0 - 2026-05-01 * Full Changelog
feat(flags): Add evaluateFlags() API for single-call flag evaluation. Returns a
FeatureFlagEvaluations snapshot you can read repeatedly without further /flags requests; pass
it to capture() via the new flags key to attach $feature/<key> and $active_feature_flags
on the captured event without an extra round trip.
feat(flags): Deprecate isFeatureEnabled(), getFeatureFlag(), getFeatureFlagResult(),
getFeatureFlagPayload(), and the send_feature_flags capture() option in favor of
evaluateFlags(). Each emits an E_USER_DEPRECATED warning pointing at the new API; existing
callers keep working unchanged until the next major version. getAllFlags() is intentionally
not deprecated — it returns an arbitrary key list the snapshot API doesn't yet cover.
fix(flags): SizeLimitedHash::contains() and add() were storing entries on the outer map and
comparing values to keys, so the per-distinct_id $feature_flag_called dedup never matched after
the first event. Both helpers now operate on a per-key set as intended.
## 4.2.4 - 2026-04-28 * Full Changelog
## 4.2.3 - 2026-04-28 * Full Changelog
One column per quarter.