# CourtKulture PHP 7.4-8.2 Compatibility Design

## Goal

Downgrade CourtKulture from its current Laravel 12 / PHP 8.2 baseline to a codebase that can run on both PHP 7.4 and PHP 8.2, while preserving the current core product behavior for staff workflows, player portal workflows, queue management, match generation, match results, and public live session views.

## Current Baseline

- Framework: Laravel 12
- Runtime: PHP 8.2+
- Frontend tooling: Vite
- Auth scaffolding: Laravel Breeze
- Test stack: PHPUnit 11

The codebase currently contains PHP 8-only syntax and Laravel 11/12 bootstrap patterns, including:

- `private readonly` promoted properties
- `match (...)`
- nullsafe operator `?->`
- `Application::configure(...)` bootstrap wiring in `bootstrap/app.php`

This means PHP 7.4 compatibility cannot be achieved through small syntax edits alone. The framework and dependency stack must also be downgraded.

## Target Platform

- Runtime target: PHP 7.4 through PHP 8.2
- Framework target: Laravel 8.83.x
- Test target: PHPUnit 9.6
- Auth target: Blade-based auth compatible with Laravel 8
- Frontend asset target: Laravel Mix, unless a simpler Laravel 8-compatible asset strategy proves more stable in this repo

Laravel 8 is the practical target because:

- Laravel 12 requires PHP 8.2+
- Laravel 9 requires PHP 8.0+
- Laravel 8 supports PHP 7.3+ and is the newest realistic Laravel line for a PHP 7.4-compatible app

## Constraints

- The app must run in both local and production environments
- The user prefers the shallowest possible downgrade, but accepts a framework downgrade if necessary
- Risk tolerance is higher than normal, but the user still wants broad feature parity
- Unrelated refactors should be avoided

## Recommended Delivery Model

Use a dedicated compatibility branch or worktree first, then merge back only after both PHP 7.4 and PHP 8.2 verification pass.

This is recommended because:

- the current branch already contains a functioning Laravel 12 application
- the migration will require coordinated package, bootstrap, syntax, and tooling changes
- isolating the downgrade reduces the chance of breaking the current working line mid-migration

## Approach Options

### Option 1: Full Laravel 8 compatibility migration in a dedicated branch

Downgrade framework, tooling, and code syntax in a staged migration until the app runs on PHP 7.4 and PHP 8.2.

Pros:

- meets the runtime goal directly
- keeps one functional app shape
- preserves the current user-facing product if completed successfully

Cons:

- highest implementation effort
- touches framework bootstrap, tooling, tests, auth, and frontend pipeline

### Option 2: Keep main on Laravel 12 and maintain a separate PHP 7.4-compatible branch long-term

Treat PHP 7.4 support as a separate distribution line.

Pros:

- lowers immediate risk to the current branch
- enables targeted compatibility work

Cons:

- creates long-term maintenance overhead
- increases feature drift risk

### Option 3: Attempt a shallow compatibility patch without framework downgrade

Keep Laravel 12 and try to backport only syntax and selected packages.

Pros:

- smallest apparent scope

Cons:

- not technically viable for PHP 7.4
- would fail at framework dependency resolution before app code matters

## Recommended Option

Option 1, executed inside an isolated compatibility branch or worktree.

This is the only realistic path that satisfies the user's requirement that the project run on PHP 7.4 through PHP 8.2 across both local and production environments.

## Migration Scope

The downgrade should be treated as a platform migration rather than a feature task.

Expected change areas:

1. Composer dependency graph
2. Laravel bootstrap and middleware registration
3. Auth scaffolding compatibility
4. Test tooling and PHPUnit compatibility
5. Frontend asset pipeline
6. PHP 8-only syntax rewrites
7. Deployment/runtime assumptions

## Architectural Design

### 1. Dependency Layer

`composer.json` and `composer.lock` will be rewritten for a Laravel 8-compatible stack.

Likely major changes:

- `php` constraint lowered from `^8.2` to a range that supports PHP 7.4 and 8.2
- `laravel/framework` downgraded from `^12.0` to `^8.83`
- `laravel/breeze` downgraded or replaced with a Laravel 8-compatible auth path
- `phpunit/phpunit` downgraded from `^11.5` to `^9.6`
- `nunomaduro/collision` downgraded to a Laravel 8-compatible release
- remove or replace developer tooling that requires newer PHP or newer Laravel, such as `laravel/pail`

### 2. Bootstrap Layer

Laravel 12 bootstrap conventions in `bootstrap/app.php` must be converted back to Laravel 8 structure:

- restore the Laravel 8 `App\Http\Kernel`
- restore exception and middleware registration through the conventional Laravel 8 application bootstrap
- ensure the custom `staff` middleware alias is registered through the Laravel 8 kernel path

### 3. Auth Layer

The current app uses Breeze-authenticated staff and player flows. The auth experience should remain Blade-based, but the implementation must be compatible with Laravel 8.

Preferred direction:

- keep the existing user-facing auth routes and Blade pages where possible
- downgrade or replace auth scaffolding with the smallest Laravel 8-compatible equivalent
- preserve current role separation:
  - staff routes remain protected
  - player portal remains protected
  - public live session view remains unauthenticated

### 4. Frontend Layer

Vite may become an unnecessary point of migration friction on Laravel 8.

Preferred direction:

- move frontend bundling to Laravel Mix if Vite support becomes cumbersome during downgrade
- preserve current Blade views and CSS/JS behavior as much as possible
- avoid redesigning UI while changing the asset pipeline

### 5. Application Code Layer

Rewrite PHP 8-only language usage into PHP 7.4-safe equivalents.

Expected conversions:

- `private readonly Foo $bar;` to standard typed properties plus constructor assignment
- `match` expressions to `switch` or lookup arrays
- nullsafe `?->` chains to explicit null checks
- any newer helper assumptions to their Laravel 8-safe equivalents

This should be done conservatively, file by file, without changing behavior unless necessary.

### 6. Testing Layer

Tests must be retained and adapted, not discarded.

Required goals:

- the suite must run on Laravel 8-compatible PHPUnit
- feature coverage around queue logic, match generation, match result recording, auth, player portal, and staff protection must stay intact
- tests that rely on Laravel 12-specific APIs must be rewritten to equivalent Laravel 8 forms

## Execution Phases

### Phase 1: Platform Skeleton

- create isolated compatibility workspace
- downgrade composer constraints
- establish Laravel 8 bootstrap/kernel structure
- restore app bootability before feature repair

### Phase 2: PHP Syntax Compatibility

- remove PHP 8-only syntax from app, routes, tests, and supporting files
- keep semantics stable

### Phase 3: Tooling and Auth Compatibility

- downgrade test/dev tooling
- settle auth scaffolding path
- settle asset pipeline path

### Phase 4: Feature Repair

- repair any regressions in:
  - staff dashboard
  - queue flow
  - match generation
  - match results
  - player registration
  - player portal
  - public live session page

### Phase 5: Runtime Verification

- verify app boots and tests pass on PHP 7.4
- verify app boots and tests pass on PHP 8.2
- verify production-critical commands for both environments

## Error Handling and Risk Management

### Primary Risks

1. Composer dead ends from package incompatibilities
2. Breeze/auth scaffolding version mismatch
3. Frontend pipeline friction between Vite-era views and Laravel 8 tooling
4. Hidden Laravel 12 assumptions in tests or route/bootstrap behavior
5. Production deployment drift between local and server environments

### Mitigations

1. Work in an isolated branch or worktree
2. Downgrade the platform in stages instead of rewriting everything at once
3. Keep user-facing behavior stable and test continuously
4. Prefer replacement of unsupported tooling over forcing partial compatibility
5. Validate on both PHP 7.4 and PHP 8.2 before claiming completion

## Non-Goals

These are not part of this migration unless they become strictly necessary:

- redesigning UI
- rewriting business rules
- adding new product features
- broad codebase cleanup unrelated to compatibility
- supporting PHP versions older than 7.4

## Verification Strategy

Minimum required verification before completion:

- composer install succeeds on the compatibility stack
- application boots successfully on PHP 7.4
- application boots successfully on PHP 8.2
- full automated test suite passes on the supported stack
- frontend assets build successfully using the chosen Laravel 8-compatible pipeline
- key manual flows remain intact:
  - staff login
  - session creation
  - add/check-in player
  - generate match
  - record result
  - player registration
  - player login
  - player portal session join/leave
  - public live view

## Decision Summary

- Goal: one codebase compatible with PHP 7.4 and PHP 8.2
- Framework target: Laravel 8
- Delivery path: isolated compatibility branch/worktree first
- Priority: make the app run reliably, even if that requires replacing newer framework/tooling conventions