Plan PHP SDK v1.1.0 modernization and completion

[roncodes]

Summary

Adds the evidence-based modernization and completion plan for the Fleetbase PHP SDK 1.1.0 release.

This is a planning-only PR. It does not yet change production code, dependencies, credentials, repository settings, the default branch, the published license, tags, or releases.

Investigation highlights

• The latest SDK tag is 1.0.2 from 2022 and the repository has no CI or release automation.
• vendor/ contains 4,394 tracked files.
• The Composer PHP constraint ^7.4 excludes all PHP 8 versions despite the README claiming “7.4 and later.”
• Syntax passes, but PSR-12 reports 23 errors and 1 warning; PHPStan 0.11 reports 28 errors.
• GitHub reports 21 dependency vulnerabilities on the default branch: 8 high and 13 moderate.
• Existing tests use a local API key and mutate live API data, so they are not a safe or credible unit/coverage baseline.
• The merged official Postman contract contains 220 requests across 36 groups, while the SDK exposes only 12 stores and one broken specialized action.
• Confirmed runtime defects include misspelled constructors, a misspelled tracking-status resource, inaccessible private members, invalid API-key validation, discarded options/hooks, and incomplete HTTP/error handling.

Plan scope

• Preserve the 1.0.2 public PHP API while rebuilding internals behind compatibility tests.
• Map every merged Postman Fleetbase/Core request to a reviewed SDK method or explicit raw-only rationale.
• Add PSR-18 transport injection with Guzzle as the default, typed services/resources, pagination, uploads/downloads, retries, and structured errors.
• Enforce 100% line and branch coverage, behavioral failure-path tests, mutation testing, static analysis, backwards-compatibility checks, and isolated Postman/SDK contract runs.
• Test PHP 7.4 through 8.5 plus lowest/latest dependency resolution and plain PHP, Laravel, and Symfony consumer fixtures.
• Add secure PR, contract, security, and protected release workflows with Packagist verification.
• Rewrite the README and replace stale badges with authoritative CI, coverage, PHP, Packagist, and license badges.
• Change the project license from MIT to AGPL-3.0-or-later for the new release, after confirming relicensing authority, while preserving the original terms of old tags.
• Migrate the default branch from master to main after branch filters, protections, badges, links, Packagist, and integrations are prepared.

Evidence sources

• fleetbase/postman origin/main at 43253dbf87e5030d95d12be019dc26fcb7151ed6
• fleetbase/core-api origin/main at b7691c06ffdfe8f8874352e746aa8e523d5e3531 (v1.6.60)
• fleetbase/fleetops origin/main at a9131daeb1a23ed4b0046dd2d7b632fb100bfba0 (v0.6.61)

Validation

• composer validate --strict — passed
• PHP syntax lint — passed for all 25 project PHP files
• git diff --check — passed
• Postman merged-contract inventory independently counted by collection and HTTP method
• PHPUnit intentionally not run because the current suite performs credentialed live mutations
• Composer audit could not reach Packagist from the sandbox; GitHub's push-time dependency report supplied the current 21-vulnerability baseline

Review focus

Please review the seven maintainer decisions in the plan, especially the PHP 7.4/8.0 compatibility bridge, precise SDK scope, release signing/approval policy, and master transition period.