[jvmvik]

Brings the PHP client in line with serpapi-ruby v1.0.3, after a feature-by-feature comparison of the two libraries. One commit per issue, all backwards compatible.

Branched from and targeting Init.

What changed

Commit	Gap closed
a1f8242	source reported php; now serpapi-php:<version>, so PHP client versions are distinguishable in usage stats
ced70fa	Constructor took only api_key/engine/timeout; now accepts default search params, and a Ruby-style config array
c47220b	var_dump($client) printed the API key in clear text; now masked via __debugInfo(), plus inspect()
08848d6	A new cURL handle per request; now one reused handle — 2.6x measured (16.3 → 42.6 req/s)
c529f01	Responses were always stdClass; new assoc option, the counterpart of Ruby's symbolize_names
88f82c7	20 engines covered vs Ruby's 38; adds the missing 19 and drops a duplicate test file
9d44a1c	No runnable examples; adds demo/ (basic, autocomplete, async, persistent benchmark) + make demo
6dddb28	Nothing type-checked the code; adds PHPStan level 6 to make analyse and CI
92a4a26	API_KEY renamed to SERPAPI_KEY to match the Ruby client and SerpApi's docs

Verification

• PHPStan level 6 over src/ and demo/: clean.
• PHPUnit: 108 tests, 0 failures. Test count went 44 → 108; the new key-free unit coverage is ClientQueryTest, ClientDefaultParamsTest, ClientInspectTest, ClientPersistentTest, ClientAssocTest.
• Persistent connections and assoc mode were verified live against the locations endpoint, which needs no API key.

For the reviewer

The 19 new engine tests have never been executed — no SerpApi key was available in the environment where this was written. They are syntax-checked and follow the existing verified pattern, but this PR's CI run is their first real execution. Please check that job before merging.

Two of them deliberately differ from their Ruby counterparts:

• google_flights / google_hotels compute dates relative to today. The Ruby specs hardcode 2025 dates that have since passed.
• google_ai_overview reads page_token from a live Google search and skips when there is no overview. The Ruby spec pins a token that has expired.

One genuine API change: search() and account() lost their : object return declarations, since they can now return arrays. The union type moved to the docblock. Everything else is additive — the positional constructor still works, and assoc defaults to false so responses stay stdClass. That last choice deliberately does not match Ruby's default, which would have broken every existing caller.

PHPStan caught a real bug in this PR's own demo_async.php: it read ->search_metadata off a value search() can return as an array, which would have been a fatal error rather than a clear message.

Two exclusions, both documented in phpstan.neon:

• tests/ is out of scope — level 6 wants a return type on every method across 40+ files for little benefit.
• One property.unusedType exclusion for the cURL handle, genuinely resource on PHP 7 and CurlHandle on PHP 8; PHPStan only analyses one version at a time.

No code style fixer was added. The codebase uses 2-space indentation, so PSR-12 enforcement would rewrite every file — that is a call for the maintainers, not a side effect of this PR.

Not included

The README documents none of the new API. close(), get_params(), assoc, persistent and the array constructor are currently undiscoverable. README.md is generated from README.md.erb via make readme, which needs erb. This was outside the agreed scope; it is the obvious follow-up, along with the missing CHANGELOG.md and CONTRIBUTING.md.

Repository secret: the workflow reads secrets.SERPAPI_KEY || secrets.API_KEY, so CI keeps working either way. Renaming the secret to SERPAPI_KEY lets that fallback be dropped later.

Also worth noting three places where this library is already ahead of Ruby and the behaviour should probably be backported: exception payloads strip api_key, parse errors omit the response body, and search_archive URL-encodes the search ID.

🤖 Generated with Claude Code

[strzibny]

@jvmvik I rebased this onto master and reworked it to match master's conventions, so it can go in without waiting on another round. Your original branch is preserved at 92a4a26, and every commit credits you as co-author.

Aligned with master

• camelCase methods and properties, PSR-12 with 2-space indentation, testXxx test names
• Kept master's md(), SERPAPI_KEY, lint job and release workflow, and ClientIntegrationTest, which now covers md()
• Replaced the assoc option with a separate searchArray(), so search() and account() keep their object return types

Fixes

• A per-call timeout now applies to that request; it was dropped from the query but never used. A per-call persistent throws instead of being silently ignored
• Clones open their own connection, and the cURL handle is left out of serialization (serializing a CurlHandle throws on PHP 8)
• Amazon searches with k, not q
• Google Videos asserts video_results, which is what the engine returns
• google_immersive_product and google_product take a page_token and product_id from a live Google Shopping search instead of hardcoded values
• AI Overview fetches its page_token with no_cache, since the token expires a minute after the search
• The async demo stops on Success (there is no Cached status), fails fast on errors, and passes async per call so it isn't also sent with every Search Archive request
• make demo did nothing: make treated the demo/ directory as an up-to-date target. It's .PHONY now
• The persistent benchmark warms up both clients before timing
• PHPStan runs once in the lint job. The >= '7.4' matrix check compared strings and ran it six times, and the ignore rule and phpVersion pin turned out to be unnecessary

Additions

• google_ai_mode example, matching the Ruby specs
• README snippets now handle assertions split over several lines, which fixes the Shopping, Autocomplete and Events examples on master

VERSION stays at 1.0.0; the bump is in #6.

PHPUnit and PHPCS pass at every commit, and PHPStan level 6 is clean.