[marandaneto]

💡 Motivation and Context

An application error callback or JsonSerializable property can throw while the SDK flushes queued events during destruction. The exception can escape either the Client or the queued consumer destructor and turn an otherwise completed web request into HTTP 500.

Catch and log Throwable at both automatic destructor boundaries. Run shutdown cleanup even when the initial flush throws, so the cache provider and file consumer resources are released.

Explicit flush() and shutdown() calls still propagate application callback and serializer exceptions, including exceptions from shutdown's final queue retry. That retry calls flush() directly rather than using the consumer's no-throw destructor. Cleanup still completes if either attempt throws, and the original first-flush return value is preserved. This deliberately preserves the SDK's existing explicit-call behavior rather than adopting the generic HTTP client spec guidance to return serialization failures as results. No public signatures or options change. This PR does not depend on the socket or timeout fixes.

💚 How did you test it?

• Added process-end regression tests for Client and direct consumer destruction, callback and serializer failures, and RuntimeException and Error. The original code exited 255. The fixed code exits normally.
• Verified that explicit calls propagate the identical exception, cache cleanup runs once, and file handles close even if flushing throws.
• Added retry regressions for a first transport failure followed by a throwing callback or serializer. Four explicit-retry cases failed on the initial PR head, then passed after separating the retry from destructor suppression. Automatic retry failures remain contained.
• Checked that shutdown preserves the first exception, the two-attempt retry behavior, the original return value, and idempotent cleanup.
• Focused suite: 32 passing tests and 190 assertions.
• Full PHPUnit suite: 1,377 passing tests and 6,982 assertions.
• Python adapter suite: 16 passing tests.
• Replayed the throwing-callback scenario under local PHP-FPM. The completed request no longer becomes HTTP 500.
• Public API and whitespace checks pass, with no new style warnings. Existing repository-wide style warnings and deprecations remain. No local coverage driver is installed.
• Final branch autoreview against origin/main passed at 42feb94282b01849f1976dd1a3ebc85abfe2f115, with no actionable findings.

📝 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

• Ran pnpm change to generate a change intent file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with Pi using worker/reviewer subagents, file tools, Git/GitHub CLI, and the isolated autoreview helper. The Pi session transcript is local and has not been published. Manoel directed the scope and requested separate, independently mergeable PRs.

These are SDK robustness fixes identified while investigating PHP runtime advisories. They do not fix PHP's runtime vulnerabilities or replace upgrading PHP. Human review is required.

[posthog]

PostHog Review · Standard · reviewed 4963214: 1 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

[github-actions]

posthog-php-lib_curl Compliance Report

Date: 2026-10-21T17:40:30.216608+00:00
Duration: 116166ms

⚠️ Some Tests Failed

46/47 tests passed, 1 failed

---

Capture Tests

⚠️ 29/30 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	28ms
Format Validation.Event Has Uuid	✅	524ms
Format Validation.Event Has Lib Properties	✅	525ms
Format Validation.Distinct Id Is String	✅	525ms
Format Validation.Token Is Present	✅	524ms
Format Validation.Custom Properties Preserved	✅	524ms
Format Validation.Event Has Timestamp	✅	526ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	524ms
Retry Behavior.Retries On 503	✅	5832ms
Retry Behavior.Does Not Retry On 400	✅	2529ms
Retry Behavior.Does Not Retry On 401	✅	2526ms
Retry Behavior.Respects Retry After Header	❌	6337ms
Retry Behavior.Implements Backoff	✅	16248ms
Retry Behavior.Retries On 500	✅	5635ms
Retry Behavior.Retries On 502	✅	5635ms
Retry Behavior.Retries On 504	✅	5633ms
Retry Behavior.Max Retries Respected	✅	17050ms
Deduplication.Generates Unique Uuids	✅	231ms
Deduplication.Preserves Uuid On Retry	✅	5633ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10831ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5145ms
Deduplication.No Duplicate Events In Batch	✅	531ms
Deduplication.Different Events Have Different Uuids	✅	527ms
Compression.Sends Gzip When Enabled	✅	527ms
Batch Format.Uses Proper Batch Structure	✅	526ms
Batch Format.Flush With No Events Sends Nothing	✅	521ms
Batch Format.Multiple Events Batched Together	✅	513ms
Error Handling.Does Not Retry On 403	✅	2527ms
Error Handling.Does Not Retry On 413	✅	2525ms
Error Handling.Retries On 408	✅	5635ms

Failures

retry_behavior.respects_retry_after_header

Retry delay too short: 804ms < 2500ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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

[github-actions]

posthog-php-fork_curl Compliance Report

Date: 2026-10-21T17:40:33.280172+00:00
Duration: 112893ms

⚠️ Some Tests Failed

36/47 tests passed, 11 failed

---

Capture Tests

⚠️ 19/30 tests passed, 11 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	34ms
Format Validation.Event Has Uuid	✅	527ms
Format Validation.Event Has Lib Properties	✅	530ms
Format Validation.Distinct Id Is String	✅	530ms
Format Validation.Token Is Present	✅	529ms
Format Validation.Custom Properties Preserved	✅	529ms
Format Validation.Event Has Timestamp	✅	530ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	531ms
Retry Behavior.Retries On 503	❌	5532ms
Retry Behavior.Does Not Retry On 400	✅	2532ms
Retry Behavior.Does Not Retry On 401	✅	2533ms
Retry Behavior.Respects Retry After Header	❌	5533ms
Retry Behavior.Implements Backoff	❌	15548ms
Retry Behavior.Retries On 500	❌	5537ms
Retry Behavior.Retries On 502	❌	5536ms
Retry Behavior.Retries On 504	❌	5533ms
Retry Behavior.Max Retries Respected	❌	15549ms
Deduplication.Generates Unique Uuids	✅	539ms
Deduplication.Preserves Uuid On Retry	❌	5535ms
Deduplication.Preserves Uuid And Timestamp On Retry	❌	10541ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	❌	5538ms
Deduplication.No Duplicate Events In Batch	✅	537ms
Deduplication.Different Events Have Different Uuids	✅	532ms
Compression.Sends Gzip When Enabled	✅	532ms
Batch Format.Uses Proper Batch Structure	✅	531ms
Batch Format.Flush With No Events Sends Nothing	✅	519ms
Batch Format.Multiple Events Batched Together	✅	521ms
Error Handling.Does Not Retry On 403	✅	2532ms
Error Handling.Does Not Retry On 413	✅	2533ms
Error Handling.Retries On 408	❌	5534ms

Failures

retry_behavior.retries_on_503

Expected at least 3 requests, got 1

retry_behavior.respects_retry_after_header

Expected at least 2 requests, got 1

retry_behavior.implements_backoff

Expected at least 3 requests, got 1

retry_behavior.retries_on_500

Expected at least 2 requests, got 1

retry_behavior.retries_on_502

Expected at least 2 requests, got 1

retry_behavior.retries_on_504

Expected at least 2 requests, got 1

retry_behavior.max_retries_respected

Expected 4 requests, got 1

deduplication.preserves_uuid_on_retry

Need at least 2 requests to check retry

deduplication.preserves_uuid_and_timestamp_on_retry

Expected at least 3 requests, got 1

deduplication.preserves_uuid_and_timestamp_on_batch_retry

Expected at least 2 requests, got 1

error_handling.retries_on_408

Expected at least 2 requests, got 1

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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

[github-actions]

posthog-php-socket Compliance Report

Date: 2026-10-21T17:40:56.541986+00:00
Duration: 149756ms

⚠️ Some Tests Failed

36/47 tests passed, 11 failed

---

Capture Tests

⚠️ 19/30 tests passed, 11 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	28ms
Format Validation.Event Has Uuid	✅	523ms
Format Validation.Event Has Lib Properties	✅	524ms
Format Validation.Distinct Id Is String	✅	524ms
Format Validation.Token Is Present	✅	525ms
Format Validation.Custom Properties Preserved	✅	524ms
Format Validation.Event Has Timestamp	✅	525ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	524ms
Retry Behavior.Retries On 503	❌	9233ms
Retry Behavior.Does Not Retry On 400	✅	2528ms
Retry Behavior.Does Not Retry On 401	✅	2527ms
Retry Behavior.Respects Retry After Header	❌	9234ms
Retry Behavior.Implements Backoff	❌	19246ms
Retry Behavior.Retries On 500	❌	9240ms
Retry Behavior.Retries On 502	❌	9236ms
Retry Behavior.Retries On 504	❌	9234ms
Retry Behavior.Max Retries Respected	❌	19248ms
Deduplication.Generates Unique Uuids	✅	534ms
Deduplication.Preserves Uuid On Retry	❌	9234ms
Deduplication.Preserves Uuid And Timestamp On Retry	❌	14242ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	❌	9239ms
Deduplication.No Duplicate Events In Batch	✅	533ms
Deduplication.Different Events Have Different Uuids	✅	527ms
Compression.Sends Gzip When Enabled	✅	524ms
Batch Format.Uses Proper Batch Structure	✅	525ms
Batch Format.Flush With No Events Sends Nothing	✅	520ms
Batch Format.Multiple Events Batched Together	✅	512ms
Error Handling.Does Not Retry On 403	✅	2526ms
Error Handling.Does Not Retry On 413	✅	2528ms
Error Handling.Retries On 408	❌	5530ms

Failures

retry_behavior.retries_on_503

Expected at least 3 requests, got 1

retry_behavior.respects_retry_after_header

Expected at least 2 requests, got 1

retry_behavior.implements_backoff

Expected at least 3 requests, got 1

retry_behavior.retries_on_500

Expected at least 2 requests, got 1

retry_behavior.retries_on_502

Expected at least 2 requests, got 1

retry_behavior.retries_on_504

Expected at least 2 requests, got 1

retry_behavior.max_retries_respected

Expected 4 requests, got 1

deduplication.preserves_uuid_on_retry

Need at least 2 requests to check retry

deduplication.preserves_uuid_and_timestamp_on_retry

Expected at least 3 requests, got 1

deduplication.preserves_uuid_and_timestamp_on_batch_retry

Expected at least 2 requests, got 1

error_handling.retries_on_408

Expected at least 2 requests, got 1

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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