feat: v2.0.0 — first-class PHP SDK rewrite

[karlwaldman]

Summary

Ground-up v2.0.0 PHP SDK for OilPriceAPI, triggered by a real customer asking for PHP example code (2026-07-02) and the ICP analysis showing our #1 buyers are embedders with an existing paying PHP segment (guzzlehttp UA: 50k reqs / 12 payers / 30d; wordpress: 60k / 20).

About v1

There was no v1: this repo was created 2025-12-16, archived, and unarchived with zero commits — no code, no README, nothing to migrate or delete. Because GitHub cannot host a PR against a commit-less repo, main was seeded with a single stub-README init commit (5402428), and this PR contains the entire SDK on top of it.

What's in the box

• Zero runtime dependencies — ext-curl + ext-json only (no Guzzle), so it runs on shared hosting and inside WordPress. PHP >= 8.1, strict_types everywhere, PSR-4 (OilPriceAPI\).
• Client — latest(?$byCode), pastDay/pastWeek/pastMonth/pastYear(?$byCode), keyless demoPrices(), and a raw()->get($path, $params) escape hatch so ANY endpoint (e.g. /v1/futures/ice-brent/curve) is reachable without an SDK release.
• Auth — Authorization: Token <key> (verified against docs.oilpriceapi.com and the Go SDK), OILPRICEAPI_KEY env fallback. Keyless client throws a helpful AuthenticationException pointing at the signup URL and demoPrices().
• Resilience — retries with exponential backoff + full jitter on 429/5xx, honors Retry-After (numeric and HTTP-date), 10s default timeout, all configurable.
• Typed exceptions — ApiException base, AuthenticationException (signup hint), RateLimitException (retryAfter, plan limit, upgrade URL), TransportException. Extracts the production nested {"error":{"message":...}} envelope (verified against the live API).
• Price DTO — immutable; code, price, currency, updatedAt (DateTimeImmutable), change24h, plus name/unit/type/formatted; toArray().
• Tests — 16 tests / 80 assertions, fully offline via an injected HttpTransport mock. Green on PHP 8.1 (Docker) and 8.5 (local).
• CI — PHP 8.1/8.2/8.3 matrix, composer validate --strict, PHPUnit. The optional live smoke step is guarded in shell ([ -z "$OILPRICEAPI_TEST_KEY" ]), never with step-level if: ${{ secrets.* }} (the bug that invalidated workflows in sibling repos); it skips gracefully since that secret is empty org-wide.
• README — quick start, a self-contained plain-PHP/no-composer cURL example (answers the customer request directly), demo-mode callout, "Beyond Oil" section (EU_CARBON_EUR, TTF futures via raw(), DIESEL_USD; maritime compliance / fleet & logistics / LNG analytics / CBAM), WordPress note linking the no-code plugin, error-handling and retry docs.

Verification

• composer validate --strict passes.
• Unit suite: 16 passed, 80 assertions on PHP 8.1.34 (Docker) and PHP 8.5.8 (local).
• Live keyless check against production: examples/quickstart.php in demo mode returns real prices from /v1/demo/prices.
• Live 401 check: SDK surfaces the API's real nested error message with the signup hint.
• README URLs verified (signup/pricing resolve 200 after www redirect; docs 200).
• NOT verified with a live paid key: the only OILPRICEAPI_KEY on this machine is stale (401 from production). The auth header format matches the docs and Go SDK exactly, but a happy-path live call with a valid key is a follow-up.

Post-merge (Karl)

• Tag v2.0.0 and submit oilpriceapi/oilpriceapi to Packagist (publication pending — manual step).
• Optionally set OILPRICEAPI_TEST_KEY org secret to activate the CI live smoke test.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@karlwaldman, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0d41e469-bdc0-49cb-8d7a-97ef65bdbca1

📥 Commits

Reviewing files that changed from the base of the PR and between 5402428 and 2828efe.

📒 Files selected for processing (21)

• .github/workflows/test.yml
• .gitignore
• CHANGELOG.md
• LICENSE
• README.md
• composer.json
• examples/quickstart.php
• examples/smoke.php
• phpunit.xml.dist
• src/Client.php
• src/Exception/ApiException.php
• src/Exception/AuthenticationException.php
• src/Exception/RateLimitException.php
• src/Exception/TransportException.php
• src/Http/CurlTransport.php
• src/Http/HttpResponse.php
• src/Http/HttpTransport.php
• src/Price.php
• src/RawClient.php
• tests/ClientTest.php
• tests/MockTransport.php

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/v2-rewrite

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}