fix: no-op when uninitialized or non-operational

[marandaneto]

💡 Motivation and Context

The PHP SDK should no-op instead of throwing into the host app when the default facade is used before PostHog::init() or when public flag APIs hit API/auth/network failures. Some facade methods also accessed the typed static client directly, which could fatal before initialization.

Changes:

• Lazily create a disabled no-op client when facade methods are called before initialization.
• Guard raw() and getFeatureFlagPayload() with the same client initialization path.
• Return empty feature flag defaults from public direct flags APIs on API errors.
• Add regression tests for uninitialized facade calls and flag API failures.

💚 How did you test it?

• vendor/bin/phpunit --do-not-fail-on-warning --do-not-fail-on-deprecation --do-not-fail-on-phpunit-deprecation --do-not-fail-on-phpunit-warning test/PostHogTest.php
• php -l lib/PostHog.php && php -l lib/Client.php && php -l test/PostHogTest.php

📝 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 changeset to generate a changeset file

[greptile-apps]

Comments Outside Diff (1)

1. lib/Client.php, line 1079 (link)

   Stale @throws Exception on fetchFeatureVariants

   After this PR, fetchFeatureVariants → fetchFlagsResponse → flags(), and flags() now catches HttpException and returns empty instead of propagating it. The @throws Exception annotation (and the identical one on the private fetchFlagsResponse) implies callers need to handle the flag-fetch failure path, but that is now handled internally. The annotation should be removed (or narrowed to document only unexpected PHP-level errors) to keep the contract accurate.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: lib/Client.php
   Line: 1079
   
   Comment:
   **Stale `@throws Exception` on `fetchFeatureVariants`**
   
   After this PR, `fetchFeatureVariants` → `fetchFlagsResponse` → `flags()`, and `flags()` now catches `HttpException` and returns empty instead of propagating it. The `@throws Exception` annotation (and the identical one on the private `fetchFlagsResponse`) implies callers need to handle the flag-fetch failure path, but that is now handled internally. The annotation should be removed (or narrowed to document only unexpected PHP-level errors) to keep the contract accurate.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
lib/PostHog.php:580
**Misleading error log when SDK is used before `init()`**

`new Client(null, ...)` triggers the constructor branch that logs `[PostHog][Client] apiKey is empty after trimming whitespace; check your project API key`. A developer who simply forgot to call `PostHog::init()` will see a message about the API key, not about the missing initialisation call, which misdirects debugging effort. Consider logging a clear message directly in `checkClient()` before creating the fallback client, e.g. `[PostHog] PostHog::init() was not called; SDK will no-op`.

### Issue 2 of 3
lib/Client.php:1079
**Stale `@throws Exception` on `fetchFeatureVariants`**

After this PR, `fetchFeatureVariants` → `fetchFlagsResponse` → `flags()`, and `flags()` now catches `HttpException` and returns empty instead of propagating it. The `@throws Exception` annotation (and the identical one on the private `fetchFlagsResponse`) implies callers need to handle the flag-fetch failure path, but that is now handled internally. The annotation should be removed (or narrowed to document only unexpected PHP-level errors) to keep the contract accurate.

### Issue 3 of 3
test/PostHogTest.php:324-344
**Prefer parameterised tests per project convention**

The team prefers parameterised tests. `testFacadeMethodsNoOpBeforeInit` packs eight independent "method X no-ops before init" assertions into one method, which means any single failure obscures the others. A `@dataProvider` that lists each `[callable, expectedValue]` pair — resetting and restoring the client per case — would make failures immediately point to the affected method and also serve as documentation of the full no-op surface.

_{Reviews (1): Last reviewed commit: "Fix feature flag error reporting" | Re-trigger Greptile}

[marandaneto]

Fixed in 5e807c9 — removed the stale @throws docs from Client::fetchFeatureVariants()/fetchFlagsResponse(). The inline Greptile items in this summary were addressed in the same commit as well.