feat!: bump minimum supported PHP version to 8.1

[gjtorikian]

Description

This PR raises our minimum supported PHP version to 8.1, which was released two years ago and reached end of official support about two months ago.

PHP 8.0 reached end of official support two years ago, and I’d like our SDKs to support only language versions that have been out of support for no more than a year.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Summary

This PR bumps the minimum supported PHP version from 7.3 to 8.1, cleans up the CI matrix to cover PHP 8.1–8.5, extracts linting into its own dedicated workflow, and upgrades several dependencies to versions that require PHP 8.x. The changes are well-structured and aligned with the library's long-term support policy.

Key points:

• paragonie/halite is upgraded from ^4.0 to ^5.1 — this is a major version jump for the cryptographic session-encryption library. Halite v5 changed its ciphertext format, which means any session data sealed with the old library version cannot be decrypted after upgrading. All active user sessions will be invalidated on upgrade. This side-effect is not documented in the PR description and should be called out explicitly in the release notes or migration guide.
• phpunit/phpunit is bumped from ^9 to ^10.5 — PHPUnit 10 has breaking changes (e.g. mandatory void return types on setUp/tearDown). Confirming existing tests pass under v10 is important.
• The new lint.yml and the existing ci.yml both only trigger on pushes to main, not next-major. Since active development happens on next-major, direct commits to that branch won't be covered by CI push triggers (though PRs will be).
• Pinning GitHub Actions steps by commit SHA is a good security practice and is consistently applied.

Confidence Score: 3/5

• Safe to merge with caution — the halite v4→v5 upgrade silently invalidates all existing user sessions and should be explicitly documented before releasing.
• The CI and tooling changes are clean and correct, but the halite major version bump is a silent breaking change for end-users: any session encrypted with v4 cannot be decrypted by v5 due to ciphertext format differences. Since this is bundled into a major version release (feat!), it is technically allowed, but it needs to be documented in release notes / migration guide to avoid user confusion. Without that documentation this PR is risky to ship as-is.
• composer.json (halite v5 ciphertext incompatibility) and lib/Session/HaliteSessionEncryption.php (the consuming code — confirm it has been tested against halite v5).

Important Files Changed

Filename	Overview
composer.json	Bumps minimum PHP to 8.1, halite to ^5.1, php-cs-fixer to ^3.0, and phpunit to ^10.5 — the halite major version jump introduces a ciphertext format incompatibility that silently invalidates all existing user sessions on upgrade.
.github/workflows/ci.yml	PHP matrix updated from [7.3, 7.4, 8.1-8.3] to [8.1-8.5]; inline lint step correctly removed in favour of the new dedicated lint workflow.
.github/workflows/lint.yml	New dedicated lint workflow pinned to PHP 8.1; push trigger only covers main, not next-major, so direct commits to the working branch will not be linted automatically.
.vscode/settings.json	New VS Code workspace settings configuring default formatters for YAML and JSON; no functional impact.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Push to main / Pull Request] --> B{Workflow Trigger}
    B --> C[CI Workflow]
    B --> D[Lint Workflow]

    C --> E[Matrix: PHP 8.1 / 8.2 / 8.3 / 8.4 / 8.5]
    E --> F[Checkout + setup-php]
    F --> G[Cache Composer packages]
    G --> H[composer install]
    H --> I[composer run-script test]

    D --> J[PHP 8.1 only]
    J --> K[Checkout + setup-php]
    K --> L[Cache Composer packages]
    L --> M[composer install]
    M --> N[composer run-script format-check]

    style A fill:#4a90d9,color:#fff
    style C fill:#27ae60,color:#fff
    style D fill:#e67e22,color:#fff
    style I fill:#27ae60,color:#fff
    style N fill:#e67e22,color:#fff

Loading

_{Last reviewed commit: "feat!: bump minimum ..."}

[greptile-apps]

Breaking change: Halite v4 → v5 ciphertext format incompatibility

Upgrading paragonie/halite from ^4.0 to ^5.1 is a breaking change for any users who have existing session data encrypted with v4. Halite embeds its own version bytes in the ciphertext format, and v5 changed this format — meaning any session cookie encrypted under v4 cannot be decrypted by v5's SymmetricCrypto::decrypt(). Users upgrading this library will have all active sessions silently invalidated and thrown as decryption exceptions.

While the PR title correctly signals a breaking change (feat!), the description only mentions the PHP version bump. It's worth explicitly documenting this session-invalidation side-effect in release notes/migration guide, and considering whether a graceful degradation path (e.g. attempt v5 decrypt, fall back to v4, then re-seal) is desirable.

[greptile-apps]

Push trigger only covers main, not next-major

The push trigger is scoped only to main, but this PR targets next-major. Any direct commits to next-major (e.g. merge commits, chore bumps) will not trigger the lint workflow — only PRs will. This matches the existing behavior of ci.yml, but it may be worth adding next-major to both push trigger lists to keep the branch continuously green:

  push:
    branches:
      - "main"
      - "next-major"

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}