125 lines
5.0 KiB
Markdown
125 lines
5.0 KiB
Markdown
# Research: Admin UI Stack Upgrade (Filament v5 + Livewire v4)
|
|
|
|
This document resolves planning unknowns for `057-filament-v5-upgrade`.
|
|
|
|
## Version Compatibility
|
|
|
|
### Decision: Upgrade to Filament v5 and Livewire v4
|
|
|
|
- Decision: Upgrade `filament/filament` to `^5` and let Composer resolve `livewire/livewire:^4` as required.
|
|
- Rationale:
|
|
- Filament v5 is the next major and current supported release.
|
|
- Livewire v4 supports Laravel 12 and PHP >= 8.1 (project is PHP 8.4.15).
|
|
- Keeps the admin UI stack aligned with upstream support/security.
|
|
- Alternatives considered:
|
|
- Stay on Filament v4: rejected (explicit goal is v5 upgrade).
|
|
- Attempt mixed-version pinning (Filament v4 plugins + Filament v5 core): rejected by spec (no mixed-version pinning).
|
|
|
|
### Evidence (Packagist)
|
|
|
|
- `filament/filament v5.0.0` requires `php:^8.2`.
|
|
- `livewire/livewire v4.x` requires `laravel/framework:^10.15|^11|^12` (Laravel 12 compatible).
|
|
|
|
## Third-Party Package Compatibility
|
|
|
|
### Decision: Remove Filament v4-only plugins and replace functionality in-app
|
|
|
|
Two Composer requirements are currently hard-pinned to Filament v4:
|
|
|
|
- `pepperfm/filament-json:^4` -> requires `filament/filament:^4.0`
|
|
- `lara-zeus/torch-filament:^2` -> requires `filament/filament:^4.0`
|
|
|
|
Because Filament v5 cannot satisfy these constraints, we must remove/replace them.
|
|
|
|
#### `pepperfm/filament-json`
|
|
|
|
- Observed in-app usage:
|
|
- `resources/views/filament/infolists/entries/snapshot-json.blade.php` includes `filament-json::json` and sets helper closures expected by the package.
|
|
- Decision:
|
|
- Replace the JSON viewer infolist entry with a first-party Blade renderer.
|
|
- Rationale:
|
|
- The app already normalizes the JSON payload and provides a "Copy JSON" action.
|
|
- A first-party renderer avoids blocking Filament v5.
|
|
- We can reuse Torchlight Engine for syntax-highlighted JSON rendering if desired.
|
|
- Alternatives considered:
|
|
- Wait for upstream Filament v5 support: rejected (would block the upgrade).
|
|
- Find another third-party Filament v5 JSON plugin: possible fallback, but first-party renderer is lowest-risk/no dependency.
|
|
|
|
#### `lara-zeus/torch-filament`
|
|
|
|
- Observed in-app usage:
|
|
- No direct usage found in `app/**` or `resources/**`.
|
|
- Torchlight rendering is implemented directly using `torchlight/engine` in Blade views (e.g. `normalized-diff` entry).
|
|
- Decision:
|
|
- Remove the package and keep `torchlight/engine` usage directly.
|
|
- Rationale:
|
|
- Removes a Filament v4-only dependency.
|
|
- Keeps the "code highlighting" feature via the engine the app already uses.
|
|
|
|
## Livewire v4 Migration Risk Areas
|
|
|
|
### Decision: Treat Livewire navigation/polling widget behavior as a primary regression surface
|
|
|
|
Observed hotspots:
|
|
|
|
- `resources/views/livewire/bulk-operation-progress.blade.php`
|
|
- Uses `wire:poll.5s="refreshRuns"`.
|
|
- Uses a JS poller that listens for `livewire:navigated` and calls `$wire.refreshRuns()`.
|
|
- `resources/views/livewire/backup-set-policy-picker-table.blade.php`
|
|
- Uses `wire:model.live`.
|
|
|
|
Rationale:
|
|
|
|
- Livewire major upgrades commonly change lifecycle events and JS hook APIs.
|
|
- Ops UX widget is global and runs across navigation; breakage would be highly visible.
|
|
|
|
Alternatives considered:
|
|
|
|
- "Upgrade and hope": rejected; we should plan explicit regression checks.
|
|
|
|
## Monitoring DB-only Guardrail Implications
|
|
|
|
### Decision: Monitoring -> Operations must remain DB-only across all Livewire requests
|
|
|
|
- Definition: "remote call" means any outbound HTTP request.
|
|
- Applies to:
|
|
- Initial render
|
|
- Background Livewire requests (polling/auto-refresh/hydration)
|
|
- Implementation implication:
|
|
- Any Livewire component used under Monitoring -> Operations must not call Graph/HTTP in lifecycle hooks.
|
|
- Remote work must remain "enqueue-only" behind explicit user actions and `OperationRun` tracking.
|
|
|
|
Alternatives considered:
|
|
|
|
- Allowing background remote calls for freshness: rejected by spec/constitution.
|
|
|
|
## Proposed Implementation Sequencing
|
|
|
|
1. Upgrade core dependencies (Filament v5 -> Livewire v4).
|
|
2. Remove/replace Filament v4-only plugins:
|
|
- Replace snapshot JSON view
|
|
- Remove torch-filament (retain torchlight/engine)
|
|
3. Run Filament upgrade command(s) and fix panel/provider issues.
|
|
4. Fix Livewire v4 regressions in polling + navigation event handling.
|
|
5. Add/adjust targeted tests and verify Monitoring DB-only behavior.
|
|
|
|
## Implementation Outcome (Final)
|
|
|
|
### Dependency decisions (as implemented)
|
|
|
|
- Filament upgraded to v5; Livewire upgraded to v4 (resolved transitively).
|
|
- Removed Filament v4-only dependencies:
|
|
- `pepperfm/filament-json`
|
|
- `lara-zeus/torch-filament`
|
|
- Kept code highlighting by explicitly requiring `torchlight/engine` (and its syntax highlighter dependency `phiki/phiki`).
|
|
|
|
### Guardrails validated
|
|
|
|
- Monitoring -> Operations remains DB-only during initial render and during background Livewire requests (no outbound HTTP).
|
|
- Monitoring -> Operations remains tenant-scoped; cross-tenant access is forbidden.
|
|
- Monitoring render does not enqueue background work; enqueue remains behind explicit user actions.
|
|
|
|
### Validation notes
|
|
|
|
- Full suite gate `php artisan test` run after upgrade.
|