docs: Add migration guides for v2 to v3 and v3 to v4 - #464
Merged
Conversation
razor-x
commented
Aug 14, 2026
razor-x
commented
Aug 14, 2026
razor-x
commented
Aug 14, 2026
Model the guide on the Python SDK's MIGRATION.md: each major version gets a summary table of breaking changes, a section per change with before/after examples, the additions worth adopting during the migration, and a checklist. The v3 to v4 guide covers the SDK unification: the Seam\Seam client with named options, the Guzzle client as the public client, the retry policy and 30-second timeout, wait_for_action_attempt replacing poll_until_ready, the namespaced nested resource classes, local enforcement of required parameters, preferred HTTP methods with the URL search params standard, and the error handling and pagination refinements. The v2 to v3 guide covers the blueprint regeneration: the two reordered get methods, the Seam\Resources and Seam\Routes namespaces, the typed action attempt result, the alphabetical nullable resource constructors, and the removed undocumented resource classes. The README's Upgrading from 3.x section links to the full guide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRhzZ42JiS7LGUynykjQXP
The Upgrading from 3.x section duplicated MIGRATION.md, which covers everything it said. Readers upgrading will find the migration guide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRhzZ42JiS7LGUynykjQXP
Every Seam SDK sends seam-sdk-name and seam-sdk-version to identify itself; only this one also rewrote User-Agent, silently discarding a caller's own value and giving no way to override it. Drop the header from sdk_headers() so a caller-set User-Agent (via guzzle_options) or the underlying HTTP library's default passes through untouched. Also drops the migration guide's now-inaccurate note on the removed SEAM_API_URL environment variable, and updates the User-Agent section to describe the corrected behavior. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRhzZ42JiS7LGUynykjQXP
Drop Seam\Seam::LTS_VERSION, Seam\SeamWithoutWorkspace::LTS_VERSION, Seam\Http\ClientFactory::LTS_VERSION, and the seam-lts-version request header, with no replacement. The other Seam SDKs (Python) carry no equivalent. Update the codegen template so a future generate keeps the constant out of src/Seam.php, and update the migration guide to describe the removal instead of pointing at Seam::LTS_VERSION. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRhzZ42JiS7LGUynykjQXP
razor-x
force-pushed
the
claude/php-migration-guides-0b4d92
branch
from
August 14, 2026 21:58
7ded7c5 to
3925ca8
Compare
Removing the SEAM_API_URL env var left the return statement without its semicolon, so src/Options.php did not parse. Every job failed on it: Lint at the syntax pass, Test and Install with a ParseError as soon as the class autoloaded, and Format and Generate when prettier could not parse the file. Return the lookup directly rather than by way of a variable that is now only used once. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRhzZ42JiS7LGUynykjQXP
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
MIGRATION.mdwith upgrade guides for both major version bumps, modeled on the Python SDK's MIGRATION.md: each guide has a summary table of breaking changes, a section per change with before/after examples, the additions worth adopting during the migration, and a checklist.v3 to v4
Covers the SDK unification as it stands on
beta(v4.0.0-beta.5):Seam\SeamreplacesSeam\SeamClient, with named constructor options and no$throw_http_errors.$seam->clientis the configured Guzzle client;Seam::request(),$seam->api_key, and the globalLTS_VERSIONconstant are removed.wait_for_action_attemptreplacespoll_until_ready, with defaults moving from 20 s/0.4 s to 10 s/1 s.DeviceProperties→Device\Properties), including the class-name-collision fix.SeamWithoutWorkspace, environment variables,SeamWebhook, andNullValue::NULL.v2 to v3
Covers the blueprint regeneration, including changes that landed in 3.x minors:
$seam->events->get()and$seam->acs->users->get()reorder their first parameter, silently breaking positional callers.Seam\Resources(3.3.0) and route clients toSeam\Routes(3.5.0).ActionAttempt->resultis typed, dropping the fields the spec defines no type for.The README's "Upgrading from 3.x" section is removed: it duplicated the guide, and migration content lives in
MIGRATION.md.Install instructions reference stable
^4/^3rather than prereleases, matching seamapi/python#615 and its follow-up.🤖 Generated with Claude Code
https://claude.ai/code/session_01WRhzZ42JiS7LGUynykjQXP