TenantAtlas/specs/102-filament-5-2-1-upgrade/research.md

Research: Filament v5.2.1 Upgrade

Feature: 102-filament-5-2-1-upgrade
Date: 2026-02-20

Upstream Notes (v5.2.0 → v5.2.1)

Source: Filament GitHub releases (v5.2.0...v5.2.1). Highlights relevant to this repo’s verification gates:

• Tenancy: "Don't register tenancy on models when it is not active"

  • Risk: Multi-panel apps may previously have had unintended tenant scoping or auto-association in a non-tenant panel.
  • Verification mapping: staging smoke must include both /admin and /system panels and check for unexpected tenant filtering or missing tenant association.

• Tables: "bulk action receives non-selectable records when using "Select all""

  • Risk: bulk actions can behave incorrectly when tables use non-selectable rows.
  • Verification mapping: smoke includes select-all + non-selectable-row scenarios.

• Testing: "Fix assertHasTableActionErrors() deprecated replacement"

  • Risk: tests relying on deprecated assertion guidance may need to follow the corrected replacement pattern.
  • Verification mapping: full suite must be green; treat any new deprecation warnings or assertion failures as regressions to address.

Decisions

Decision: Upgrade Filament constraint to ^5.2.1

• Rationale:
  • Patch-level stability/bugfix upgrade with known fixes relevant to this app (tenancy registration behavior; table bulk selection; testing assertions).
  • Keeps us current within Filament v5 and reduces upgrade debt.
• Alternatives considered:
  • Stay on ^5.0 until a larger upgrade window is available (rejected: leaves known upstream fixes unconsumed).

Decision: Allow plugin/extension dependency bumps (Composer-only) in the same PR

• Rationale:
  • Patch upgrades can be blocked by transitive constraints; allowing composer-only plugin bumps preserves the “dependency-only” scope.
  • Avoids splitting into multiple PRs that each touch composer.lock while still preventing application code changes.
• Alternatives considered:
  • Strict Filament-only bump; abort on plugin incompatibility (rejected: increases likelihood of blocking the upgrade).
  • Allow minimal application code compatibility fixes (rejected: conflicts with “no feature changes” scope).

Decision: Verification gates

• Automated gate (required): Full automated regression suite + frontend build

  • Rationale: ensures both PHP/Livewire/Filament and frontend asset pipeline remain stable.
  • Alternatives considered: tests-only (rejected: build failures often surface asset regressions).

• Manual gate (required): Staging UI smoke for Admin (/admin) and System (/system, if present)

  • Rationale: catches runtime regressions that can slip past tests (modals, table selection, tenancy-related UI behavior).
  • Alternatives considered: local-only smoke (rejected: staging is closer to production and aligns with rollback criteria).

Decision: Rollback strategy

• Rationale:
  • Fastest safe rollback is to revert composer.lock (and the Filament constraint if changed) and redeploy the last known-good artifact.
• Alternatives considered:
  • “Forward fix” under pressure (rejected: increases outage window and risk).

Implementation Outcome Notes (2026-02-20)

• Filament was upgraded to v5.2.1 successfully.
• No additional Filament plugin/extension constraints were required in composer.json (no plugin bumps).
• Composer resolution included transitive framework updates (not plugin-specific), including Laravel v12.52.0 and Livewire v4.1.4.
• During verification, a tenant-scope regression surfaced in backup-set listing tests after the upgrade; mitigation was applied by explicitly scoping BackupSetResource queries to the active tenant.