release: add inspections API in PHP SDK 1.4.0

[roncodes]

Summary

Implement the six driver-facing inspection endpoints from fleetbase/postman#60 and prepare SDK 1.4.0 without changing existing consumers.

• Add InspectionForm and Inspection resources and services with property and accessor access.
• Map form list/retrieve, inspection submit/list/retrieve, and vehicles->listVehicleInspections to their correct services.
• Preserve positional identifiers, direct payload/filter arrays, final request options, and legacy envelopes. Pass caller-supplied Idempotency-Key headers and typed custom_field_values unchanged.
• Regenerate all 270 contract mappings and executable examples, and add the published 1.3.0 API compatibility snapshot.
• Update README, changelog, release notes and checklist.

Live contract and upstream dependency

Postman #60 is merged, including #61 which fixes submission JSON Content-Type. Fleetbase #652 has merged the inspection seed. Fleet-Ops #319 is still open at preparation time.

The lock pins Postman d6a7cc5, Fleetbase a5dea4b, and Fleet-Ops inspection source 0d11583. CI overlays that exact package using the canonical Fleetbase sequence (replace package, rebuild classmap, clear caches, migrate, reload Octane), BEFORE minting and seeding fixtures. This verifies the actual inspection implementation rather than the older published image. Source overlay behavior is recorded in job summaries.

Release approval must confirm the inspection API is available in the intended Fleetbase deployment. A green pinned-source run does not establish published-image availability. No upstream PR is merged by this change.

Validation

• Local PHPUnit: 41 tests, 4,749 assertions.
• Xdebug 3.5.3: 100% line and branch coverage.
• All 270 contract requests mapped; public API compatibility passes through 1.3.0.
• Static analysis, formatting, Composer validation, actionlint, and release identity checks pass.
• GitHub checks, mutation, release-candidate dry run, and disposable SDK contract must all pass before review handoff.

Website coordination

A separate fleetbase.io PR removes the PHP completeness gate from the Postman bump, restores the no-change guard, and generates inspection API docs independently of SDK release timing. The website can merge its fix independently. Synchronize the new PHP catalog after 1.4.0 is published.

Merging this release/1.4.0 branch triggers normal release validation and the protected release environment. No merge, tag, or publication has been performed.

[roncodes]

Final live-contract result: blocked by an upstream Fleet-Ops inspection bug, not ready to merge.

The exact pinned implementation 0d11583 passes source overlay, migrations, health checks, seeding, form listing, and form retrieval. Submit an Inspection reaches the API with JSON including location coordinates, but fails with HTTP 500: SQLSTATE HY000 / 1364, field location does not have a default value. InspectionSubmission::createIssueFromFailures() creates an Issue without its required spatial location. The latest head of Fleet-Ops PR #319 is still the same revision and still omits this field. The subsequent retrieve fails because no successful submission ID was returned.

Evidence: https://github.com/fleetbase/fleetbase-php/actions/runs/34694049246
Upstream implementation: https://github.com/fleetbase/fleetops/blob/0d11583d0484ad04761ca0cd6a1025cec4aed91c/server/src/Models/InspectionSubmission.php#L317

All other 30 SDK checks passed, including 100% line/branch coverage, 87.86% mutation, PHP compatibility, consumer fixtures, and the release-candidate dry run. Candidate archive and SBOM checksums verified; archive contains 144 files with no forbidden development state.

The separate website fix fleetbase/fleetbase.io#99 has all checks green, including Vercel, and can merge independently. No inspection assertions or seed behavior were weakened to hide this server failure. Completing this SDK release requires correcting the upstream Issue location assignment, repinning the tested source, and rerunning the full contract.

[roncodes]

Confirmed, and fixed upstream: fleetbase/fleetops#319 now carries 2e130a79.

Cause. issues.location is $table->point('location') — spatial, not nullable, no default. InspectionSubmission::createIssueFromFailures() built the Issue without it, so MySQL refused the insert with 1364 and the submit answered 500. It only fires when a submission has a failed item and the form has create_issue_on_failure, which is why the form list and retrieve steps passed.

Fix. The issue now takes where the failure was reported: the submission's own coordinates, else the vehicle's last known position, else the driver's, else an empty point. Read directly rather than through Utils::getPointFromMixed(), which throws rather than answering null when it cannot resolve a point, and each of those sources is routinely empty. The work order path needed nothing: work_orders has no such column.

Why no test caught it. The inspection test harnesses stub ST_GeomFromText for SQLite and handed back the WKT they were given, so a stored point could never be read again and no test ever stored one. The stub now answers the way MySQL does, a 4-byte SRID followed by the geometry's WKB, and the tests cover an issue taking the submission's coordinates, the vehicle's, and the empty point.

To repin. 2e130a79 on feature/inspections-driver-api. Its PHP CI — lint, the full suite and the 100% coverage gate — is running on that head; local runs of the inspection suites pass. Worth knowing before you rerun the contract: the Fleet-Ops contract job itself is still red for an unrelated reason, fleetbase/postman#61. Submit an Inspection rebuilds its body in a pre-request script, and pm.request.body.update() dropped the raw JSON language, so the body went out as text/plain and the API parsed none of it. If your SDK run sends the submit as JSON it will not hit that, but the collection at postman main does until #61 merges.

[roncodes]

Follow-up: fleetbase/fleetops#319 is green on db671b6f — lint, the full suite, the 100% coverage gate, and the live Postman contract, which exercises a driver submit end to end for the first time. The text/plain caveat in my last comment is gone: fleetbase/postman#61 has merged.

Repin to db671b6f. 2e130a79 carries the location fix itself; db671b6f only adds the matching stub to a third test harness, so either works for a source overlay.