[paketeserrano]

Summary

Replace the legacy implementation with the generated v4 PHP SDK while preserving the Composer package name upcloudltd/upcloud-php-api, repository URL, and all historical v1-v3 tags. This is a breaking major-version replacement, not a drop-in v3 upgrade. No release tag is included.

• Add root Composer packaging/autoloading and preserve metadata through regeneration.
• Retarget repository/docs links and document v3-to-v4 migration and alpha releases.
• Harden release provenance, default-branch ancestry, spec-download URLs and exact Packagist source/archive verification.
• Use repository-level secrets only; support numeric alpha/beta/RC tags.
• Preserve @UpCloudLtd/devex @Darep ownership.

Validation

Rehearsed the merge locally on a separate branch from the same main baseline; no conflicts and an exact resulting-tree match to this import.

• PHP 8.2: 525 PHPUnit/WireMock tests and 1,138 assertions passed; no failures or skips.
• 21 Python tests and 10 offline release/workflow regressions passed.
• Generated smoke test: 1,354 PHP files, 312 enums and 29 service clients passed.
• All 487 OpenAPI operations covered; request/model fixtures passed.
• PHPStan max level: no errors across 1,398 source/test files.
• Actionlint passed for six workflows; archive Composer install/autoload passed.
• Rendered docs: 5 pages, 139 local links and 1,447 method disclosures verified.

These are local results; GitHub PHP 8.1/8.2 CI must also pass before merge.

Remaining Gates

• Configure required status checks using this PR's actual CI job names.
• Enable/verify Pages after the migrated docs reach main.
• Coordinate the upstream regeneration target cutover after the new workflow exists on main.
• Docs PRs created with GITHUB_TOKEN do not automatically start CI; that finding is deliberately deferred and needs a manual/later solution.
• Secret names are configured, but live spec-download and publishing authorization remain to be verified.

PACKAGIST_PUBLISH_ENABLED=false; the legacy Packagist push webhook is disabled. Pushing a release tag can still make it discoverable by Packagist scans. Do not merge or publish an alpha until separately approved.