[WIP] Forge v2 SDK Update (New Version)#204
Open
PeteBishwhip wants to merge 113 commits into
Open
Conversation
- Change base URL from /api/v1 to /api (v2) - Update Content-Type to application/vnd.api+json (JSON:API spec) - Add PATCH method support for partial updates - Update User-Agent to Laravel Forge PHP/4.0
- Add ManagesOrganizations trait with 7 endpoints - Add Organization resource - All API v2 endpoints are organization-scoped
- Add ManagesProviders trait (8 endpoints) - Add ManagesServerCredentials trait - Add Provider, ProviderRegion, ProviderSize, ServerCredential, VPC resources - Support for cloud provider integration
- Add ManagesTeams trait (13 endpoints) - Add ManagesRoles trait (10 endpoints) - Add Team, TeamMember, TeamInvitation resources - Add Role, Permission, PredefinedRole resources - Support for collaborative team management
- Add ManagesUser trait - Support for fetching authenticated user profile
- Update ManagesServers trait to organization-scoped endpoints - Add PHP version management support (43 total endpoints) - Enhanced server lifecycle management
- Update ManagesSites trait for API v2 (42 endpoints) - Add ManagesWebhooks and ManagesWorkers traits - Add Domain and Heartbeat resources - Certificate management now integrated with sites - Support for custom domains and health monitoring
- Add ManagesDeployments trait (16 endpoints) - Add Deployment resource - Support for deployment scripts, webhooks, and history
- Add ManagesIntegrations trait (20 endpoints) - Add Integration resource - Support for Horizon, Octane, Reverb, Pulse, Inertia, Maintenance, and Scheduler - Enhanced Laravel ecosystem integration
- Update ManagesDatabases trait (11 endpoints) - Merge database user management into unified trait - Remove separate ManagesDatabaseUsers trait
- Rename ManagesDaemons to ManagesBackgroundProcesses - Rename Daemon resource to BackgroundProcess - Update for API v2 organization-scoped endpoints (6 endpoints) - Remove old daemon trait and resource
- Rename ManagesJobs to ManagesScheduledJobs - Rename Job resource to ScheduledJob - Update for API v2 organization-scoped endpoints (5 endpoints) - Remove old job trait and resource
- Rename ManagesSiteCommands to ManagesCommands - Rename SiteCommand resource to Command - Update for API v2 organization-scoped endpoints (5 endpoints) - Remove old site command trait and resource
- Update ManagesFirewallRules, ManagesSecurityRules, ManagesRedirectRules - Update ManagesNginx, ManagesNginxTemplates - Update ManagesMonitors, ManagesSSHKeys, ManagesCredentials - Update ManagesRecipes with RecipeRun and ForgeRecipe resources - Add ManagesLogs for server and site logging - All traits now organization-scoped
Add backup configurations and backup management functionality.
Update link to official Forge API documentation
Drop serverName (not in spec) and add organizationId so SDK-injected context hydrates.
Drop output (lives on the separate CommandOutputResource endpoint, not on CommandResource attributes). Add organizationId and serverId so the SDK-injected context hydrates.
DomainRecordResource does not expose a primary flag.
The previous commit dropped the dead Domain::primary property; the test was asserting on it. Switch to allow_wildcard_subdomains which is a real spec attribute.
RecipeResource exposes only name, script, user, created_at, updated_at.
SecurityRuleResource exposes name, path, status, created_at, updated_at; the credentials field is not returned by the API.
TeamResource, CustomRoleResource, PermissionResource, and PredefinedRoleResource each expose only a name (plus timestamps where applicable). The description and category properties were carry-overs and would never hydrate.
Drop userId, roleId, and role — the API MembershipResource exposes only name, email, created_at, updated_at. Add organizationId so SDK-injected context hydrates.
The previous commit dropped TeamMember::role (not in spec). Update the test to assert against name/email which are real MembershipResource attributes.
Drop roleId and expiresAt (not in spec). Add organizationId so the SDK-injected context hydrates.
Drop createdAt (not in spec). Add organizationId and credentialId so the SDK-injected URL context hydrates onto the resource.
ServerResource does not expose a network attribute. The network/peer
list is a separate endpoint (servers/{server}/network).
The load-balancing-nodes endpoint is cursor-paginated per the spec (page[size]/page[cursor]; meta.next_cursor/per_page). Previously the SDK returned a flat array of raw arrays, discarding pagination meta and never hydrating items as resources. Add a LoadBalancingNode resource matching LoadBalancingNodeResource and switch the method to paginatedCollection.
DatabaseUserResource exposes only name, status, created_at, updated_at. The databases array is a JSON:API relationship which Resource::fill() strips, so this property would never be hydrated.
Tags are a JSON:API relationship which Resource::fill() strips along with relationships/links. The dead $tags array properties (and the tags() string helpers that read them) would never return real data.
OrganizationResource no longer declares ownerId (the field is not in the OpenAPI spec). The test was hydrating a synthetic payload that included owner_id and asserting on it.
The composer-credentials and npm-credentials endpoints return resource arrays per the spec (ComposerCredentialResource and NpmCredentialResource). Previously the SDK returned raw arrays of arrays; now each item is hydrated into a ComposerCredential or NpmCredential resource with URL context injected, matching the pattern used by every other typed-resource list method.
The OpenAPI spec declares 202 no-body responses for 10 mutation endpoints that US-007/US-008 promoted to typed resource returns. Returning newResource(Class::class, []) produced an empty stub with every property nulled out — worse than void because callers think they have data. Treat OpenAPI as authoritative: 202-no-body endpoints stay : void. Reverted: installPhpVersion, updateSite, createRecipeRun, createBackupConfiguration, updateBackupConfiguration, createBackup, updateBackgroundProcess, updateDatabaseUser, updateComposerCredential, updateNpmCredential, plus the matching resource convenience methods on Server, Recipe, BackupConfiguration. Site::updateDeploymentScript stays typed (spec confirms 200 with DeploymentScriptResource body).
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
5 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.
This pull request introduces major API changes and new features for the Laravel Forge SDK, preparing for a v4.0.0 release. The most important updates are the addition of organization-scoped endpoints, new resource management traits, and breaking changes to existing interfaces. These changes modernize the SDK, expand its functionality, and drop support for legacy PHP versions.
API and Resource Management Enhancements:
ManagesBackgroundProcesses) and site commands (ManagesCommands) with full CRUD and log/output retrieval, all using organization-scoped endpoints. [1] [2]ManagesBackupsto support organization-scoped backup configurations, backup instances, creation, deletion, and restoration, replacing previous server-only endpoints.Breaking Changes and Cleanup:
composer.jsonto require PHP 8.0+ and addedlaravel/pintfor code style, reflecting the drop of PHP 7 support and modernization of development tooling.Release and Testing Updates:
CHANGELOG.mdto mark these breaking changes and enhancements.phpunit.xml.distto use PHPUnit 10.x schema and cache, improving test configuration and compatibility.