fix: normalize SDK timestamps to UTC

[marandaneto]

💡 Motivation and Context

The SDK serializes event timestamps in UTC, but the public capture, identify, and alias PHPDoc did not describe the accepted timestamp types or the timezone behavior. This makes the contract explicit for both the client and static APIs. Integer and float values represent epoch seconds, parseable strings may include a timezone offset, and null uses the SDK-generated timestamp. A timestamp with another timezone is serialized as the equivalent UTC instant.

This also adds regression coverage for identify and alias. The test changes the PHP default timezone to America/Los_Angeles, sends both calls with 2022-05-01T05:30:00+05:30, and verifies that the $identify and $create_alias events both contain 2022-05-01T00:00:00+00:00.

💚 How did you test it?

• vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml --no-coverage --filter testIdentifyAndAliasTimestampsAreFormattedInUtc test/PostHogTest.php
• vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml --no-coverage test/ - 451 tests and 3,830 assertions passed.
• composer validate --no-check-publish
• composer run api:check
• vendor/bin/phpcs --standard=phpcs.xml lib/Client.php lib/PostHog.php test/PostHogTest.php reported no errors. It still exits with existing warnings on unchanged lines.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Added a patch change intent file.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Pi's worker agent helped reconcile the change with the latest main, run validation and autoreview, and prepare this draft PR. A public session link is not available from this environment. The newly landed timestamp formatter was kept unchanged, while this PR retains the missing public API documentation and focused identify and alias regression coverage.

[github-actions]

posthog-php Compliance Report

Date: 2026-08-14 11:47:45 UTC
Duration: 95257ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	12ms
Format Validation.Event Has Uuid	✅	5ms
Format Validation.Event Has Lib Properties	✅	6ms
Format Validation.Distinct Id Is String	✅	5ms
Format Validation.Token Is Present	✅	5ms
Format Validation.Custom Properties Preserved	✅	5ms
Format Validation.Event Has Timestamp	✅	5ms
Retry Behavior.Retries On 503	✅	5315ms
Retry Behavior.Does Not Retry On 400	✅	2009ms
Retry Behavior.Does Not Retry On 401	✅	2010ms
Retry Behavior.Respects Retry After Header	✅	8011ms
Retry Behavior.Implements Backoff	✅	15729ms
Retry Behavior.Retries On 500	✅	5116ms
Retry Behavior.Retries On 502	✅	5115ms
Retry Behavior.Retries On 504	✅	5111ms
Retry Behavior.Max Retries Respected	✅	16520ms
Deduplication.Generates Unique Uuids	✅	11ms
Deduplication.Preserves Uuid On Retry	✅	5114ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10312ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5118ms
Deduplication.No Duplicate Events In Batch	✅	11ms
Deduplication.Different Events Have Different Uuids	✅	6ms
Compression.Sends Gzip When Enabled	✅	6ms
Batch Format.Uses Proper Batch Structure	✅	5ms
Batch Format.Flush With No Events Sends Nothing	✅	3ms
Batch Format.Multiple Events Batched Together	✅	8ms
Error Handling.Does Not Retry On 403	✅	2008ms
Error Handling.Does Not Retry On 413	✅	2010ms
Error Handling.Retries On 408	✅	5115ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	7ms
Request Payload.Flags Request Uses V2 Query Param	✅	5ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	5ms
Request Payload.Flags Request Omits Authorization Header	✅	4ms
Request Payload.Token In Flags Body Matches Init	✅	5ms
Request Payload.Groups Round Trip	✅	4ms
Request Payload.Groups Default To Empty Object	✅	5ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	4ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	5ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	4ms
Request Lifecycle.No Flags Request On Init Alone	✅	2ms
Request Lifecycle.No Flags Request On Normal Capture	✅	5ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	7ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	5ms
Retry Behavior.Retries Flags On 502	✅	106ms
Retry Behavior.Retries Flags On 504	✅	109ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	8ms

[greptile-apps]

_{Reviews (1): Last reviewed commit: "chore: remove changeset" | Re-trigger Greptile}

[arnohillen]

(created by claude code)

[arno's agent] Verified at 3ddc93a: docs-and-tests-only, the documented formatter already converts offset inputs to the UTC instant (never relabels) with the regression test proving +05:30 to Z conversion under a non-UTC default timezone; CI fully green including 46/46 compliance.

[arnohillen]

(created by claude code)

[arno's agent] The checklist still marks 'Added a patch change intent file' but 3ddc93a removed .changeset/calm-owls-drift.md, so the final diff contains no change intent.

[arnohillen]

(created by claude code)

[arno's agent] formatTime treats falsy timestamps (0, 0.0, '') the same as null and substitutes the SDK clock, which the new int|float|string|null docblock does not mention.

[marandaneto]

@arnohillen Good catch! Fixed in cba068b — integer and float zero timestamps now serialize as the Unix epoch instead of using the SDK clock. The PHPDoc now documents epoch-number, parseable-string, and null/invalid fallback behavior, with regression coverage for both 0 and 0.0.

[marandaneto]

@arnohillen Fixed in cba068b — restored the patch change intent file so the checklist now matches the PR diff.