Modernize and complete the Fleetbase PHP SDK

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1,17 @@
+* text=auto eol=lf
+
+/.github export-ignore
+/contracts export-ignore
+/docs export-ignore
+/fixtures export-ignore
+/tests export-ignore
+/tools export-ignore
+/.editorconfig export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.php-cs-fixer.dist.php export-ignore
+/composer.lock export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml.dist export-ignore
+/phpunit-9.xml.dist export-ignore
+/infection.json5.dist export-ignore

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+custom:
+  - https://fleetbase.io

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Report a reproducible SDK defect
+title: "[Bug]: "
+labels: [bug, needs-triage]
+body:
+  - type: markdown
+    attributes:
+      value: Do not include API keys, authorization headers, personal data, or production payloads. Report vulnerabilities through the Security tab.
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK version
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: PHP, Composer, framework, and Fleetbase API versions
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal sanitized reproduction
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/fleetbase/fleetbase-php/security/advisories/new
+    about: Report vulnerabilities privately.
+  - name: Usage support
+    url: https://github.com/fleetbase/fleetbase-php/discussions
+    about: Ask installation and usage questions.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose an SDK capability or API mapping
+title: "[Feature]: "
+labels: [enhancement, needs-triage]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem and use case
+    validations:
+      required: true
+  - type: input
+    id: contract
+    attributes:
+      label: Official Postman request or API documentation link
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed PHP API
+    validations:
+      required: true
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility considerations

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+## Contract source and endpoints
+
+## Compatibility classification
+
+- [ ] Additive
+- [ ] Bug fix
+- [ ] Deprecation
+- [ ] Breaking change (requires a major release)
+
+## Verification
+
+- [ ] Unit and fixture tests
+- [ ] Fresh line and branch coverage
+- [ ] Static analysis and formatting
+- [ ] API snapshot and contract checks
+- [ ] Consumer fixtures where applicable
+
+## Documentation, security, and credentials
+
+Describe documentation changes, security impact, credential handling, exact commands run, and known limits.

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: composer
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      composer-development:
+        dependency-type: development
+      composer-runtime:
+        dependency-type: production
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10

.github/workflows/ci.yml

@@ -0,0 +1,245 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+      - release/**
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality and contracts
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up PHP
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: "8.2"
+          coverage: none
+          tools: composer:v2
+      - name: Validate Composer metadata
+        run: composer validate --strict
+      - name: Install locked dependencies
+        run: composer install --no-interaction --prefer-dist
+      - name: Run quality and contract gates
+        run: composer check
+
+  compatibility:
+    name: PHP ${{ matrix.php }} / ${{ matrix.dependencies }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["7.4", "8.0", "8.1", "8.2", "8.3", "8.4", "8.5"]
+        dependencies: [lowest, latest]
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up PHP
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+      - name: Resolve dependencies
+        run: composer update --no-interaction --prefer-dist ${{ matrix.dependencies == 'lowest' && '--prefer-lowest' || '' }}
+      - name: Run hermetic unit tests
+        run: composer test:unit
+
+  coverage:
+    name: Coverage evidence
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up PHP with Xdebug
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: "8.2"
+          coverage: xdebug
+          tools: composer:v2
+      - name: Install locked dependencies
+        run: composer install --no-interaction --prefer-dist
+      - name: Generate fresh line and branch coverage
+        run: composer test:coverage
+        env:
+          XDEBUG_MODE: coverage
+      - name: Print coverage summary
+        run: |
+          cat build/coverage/summary.txt
+          php tools/report-uncovered.php build/coverage/clover.xml
+          php tools/report-uncovered-branches.php build/coverage/coverage.php
+      - name: Enforce complete line and branch coverage
+        run: php tools/check-coverage.php build/coverage/summary.txt 100
+      - name: Upload fresh coverage evidence
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage-evidence
+          path: |
+            build/coverage/clover.xml
+            build/coverage/cobertura.xml
+            build/coverage/summary.txt
+          if-no-files-found: error
+          retention-days: 14
+
+  mutation:
+    name: Mutation baseline
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up PHP with Xdebug
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: "8.3"
+          coverage: xdebug
+          tools: composer:v2
+      - name: Install locked dependencies
+        run: composer install --no-interaction --prefer-dist
+      - name: Download and verify Infection 0.35.3
+        run: |
+          curl --fail --location --silent --show-error --output /tmp/infection.phar https://github.com/infection/infection/releases/download/0.35.3/infection.phar
+          echo "f7109fe91555eba08657c789a55377a1d27809fdb50d553de5654b196eb221aa  /tmp/infection.phar" | sha256sum --check
+      - name: Run full-source mutation baseline
+        run: php /tmp/infection.phar --configuration=infection.json5.dist --no-progress
+        env:
+          XDEBUG_MODE: coverage
+      - name: Print mutation summary
+        if: always()
+        run: cat build/mutation/summary.log
+      - name: Upload mutation evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: mutation-evidence
+          path: build/mutation/
+          if-no-files-found: warn
+          retention-days: 14
+
+  consumers:
+    name: ${{ matrix.fixture }} consumer
+    needs: archive
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        fixture: [plain, laravel, symfony]
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up PHP
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: "8.2"
+          coverage: none
+          tools: composer:v2
+      - name: Download inspected source archive
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distribution-archive
+          path: build/dist
+      - name: Prepare archive-backed package repository
+        run: |
+          mkdir -p build/consumer-source
+          tar -xzf build/dist/fleetbase-php-dev.tar.gz -C build/consumer-source
+          php tools/configure-consumer-fixture.php "fixtures/consumer/${{ matrix.fixture }}" "build/consumer-source/fleetbase-php-dev"
+      - name: Install consumer from inspected archive
+        run: composer update --working-dir=fixtures/consumer/${{ matrix.fixture }} --no-interaction --prefer-dist
+      - name: Verify framework integration
+        run: composer verify --working-dir=fixtures/consumer/${{ matrix.fixture }}
+      - name: Verify optimized production autoloading
+        run: composer install --working-dir=fixtures/consumer/${{ matrix.fixture }} --no-interaction --no-dev --optimize-autoloader
+
+  archive:
+    name: Distribution archive
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up PHP
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: "8.2"
+          coverage: none
+      - name: Build deterministic source archive
+        run: |
+          mkdir -p build/dist
+          git archive --format=tar.gz --prefix=fleetbase-php-dev/ --output=build/dist/fleetbase-php-dev.tar.gz HEAD
+      - name: Inspect distribution contents
+        run: php tools/check-release-archive.php build/dist/fleetbase-php-dev.tar.gz
+      - name: Upload inspected source archive
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distribution-archive
+          path: build/dist/fleetbase-php-dev.tar.gz
+          if-no-files-found: error
+          retention-days: 14
+
+  release-candidate:
+    name: Release candidate dry run
+    needs: [quality, compatibility, coverage, mutation, consumers, archive]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out complete source history
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Set up PHP and Composer
+        uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
+        with:
+          php-version: "8.2"
+          coverage: none
+          tools: composer:v2
+      - name: Validate release identity and dependency security
+        run: |
+          php tools/check-release-version.php 1.1.0 --allow-non-main
+          composer audit --locked --no-interaction
+      - name: Download exact coverage evidence
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: coverage-evidence
+          path: build/coverage
+      - name: Build and inspect the release archive
+        run: |
+          mkdir -p build/release-candidate
+          git archive --format=tar.gz --prefix=fleetbase-php-1.1.0/ --output=build/release-candidate/fleetbase-php-1.1.0.tar.gz HEAD
+          php tools/check-release-archive.php build/release-candidate/fleetbase-php-1.1.0.tar.gz
+      - name: Generate CycloneDX SBOM
+        uses: anchore/sbom-action@3ad7283483fc7af8ff2b4ea19663c2d5ca935e26 # v0.24.2
+        with:
+          path: .
+          format: cyclonedx-json
+          output-file: build/release-candidate/fleetbase-php-1.1.0.sbom.cdx.json
+          upload-artifact: false
+          dependency-snapshot: false
+      - name: Collect release evidence and checksums
+        run: |
+          cp build/coverage/summary.txt build/release-candidate/coverage-summary.txt
+          cp docs/api-coverage.md build/release-candidate/api-coverage.md
+          cd build/release-candidate
+          sha256sum fleetbase-php-* > SHA256SUMS
+      - name: Upload complete release candidate
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: fleetbase-php-1.1.0-release-candidate
+          path: build/release-candidate/
+          if-no-files-found: error
+          retention-days: 30