Filacheck Laravel Package

Technical Evaluation

Architecture Fit

• Highly Complementary: FilaCheck is designed specifically for Filament v4/v5 projects, aligning perfectly with Laravel-based admin panel architectures. It integrates seamlessly into the Laravel ecosystem (e.g., vendor/bin CLI tools, composer dependencies) without requiring architectural changes.
• Rule-Based Static Analysis: Leverages PHP AST (Abstract Syntax Tree) parsing (via phpstan/phpstan under the hood), making it lightweight yet powerful for detecting deprecated patterns, anti-patterns, and best-practice violations in Filament-specific code.
• Extensibility: Supports custom rule configuration (via filacheck.php) and Pro version for advanced use cases, allowing gradual adoption.

Integration Feasibility

• Minimal Friction: Requires only a single composer require and zero Laravel service provider/configuration. Works out-of-the-box with Filament’s default directory structure (app/Filament).
• CI/CD Ready: Designed for pre-commit hooks (e.g., Laravel Pint’s --dirty equivalent) and GitHub Actions, with exit codes (0/1) for pipeline integration.
• Backward Compatibility: Safe to run on existing Filament v4/v5 projects without breaking changes. Rules are opt-in/opt-out via config.

Technical Risk

Key Questions for TPM

1. Adoption Scope:
   • Should FilaCheck run in CI (blocking) or developer environments (non-blocking)?
   • Will the team use auto-fix (--fix) or prefer manual review?
2. Rule Prioritization:
   • Which deprecated rules (e.g., reactive() → live()) are critical for the project’s Filament version?
   • Should Pro rules (e.g., too-many-columns) be adopted later for performance tuning?
3. Integration Depth:
   • Should it replace or complement existing tools (e.g., PHPStan, Pest)?
   • Can it integrate with Laravel Forge/Envoyer for deployment checks?
4. Maintenance:
   • Who will update rules as Filament evolves (e.g., new deprecations in v5)?
   • Should the config be version-controlled or managed centrally?

Integration Approach

Stack Fit

• Native Laravel Compatibility: Works with Laravel 9+, Filament v4/v5, and PHP 8.1+. No framework modifications required.
• Toolchain Synergy:
  • CI/CD: Integrates with GitHub Actions, GitLab CI, or Laravel Forge pipelines.
  • Local Dev: Compatible with Laravel Sail, Laravel Valet, and PHPStorm (via vendor/bin).
  • Pre-Commit: Can be added to Husky or Laravel Git Hooks alongside Pint/CS Fixer.
• Dependency Graph:

  Laravel → Filament → FilaCheck (Static Analysis)
  ↑               ↑
  Composer       PHP AST
  

Migration Path

1. Pilot Phase (Low Risk):

   • Install as a dev dependency:

     composer require laraveldaily/filacheck --dev
     

   • Run manually to audit existing codebase:

     vendor/bin/filacheck --detailed
     

   • Disable problematic rules in config/filacheck.php if needed.

2. CI Integration (Medium Risk):

   • Add to GitHub Actions (example provided in README).
   • Start with non-blocking runs (exit code 1 ignored).
   • Gradually enforce critical rules (e.g., deprecated-reactive).

3. Auto-Fix Adoption (High Risk):

   • Use --dry-run to preview fixes before enabling --fix.
   • Restrict to specific directories (e.g., Resources/).
   • Monitor for regressions in PRs.

4. Pro Version (Optional):

   • Evaluate performance/security rules for long-term adoption.
   • Justify cost based on developer productivity gains.

Compatibility

Sequencing

1. Phase 1: Audit (2–4 weeks)

   • Run FilaCheck on the entire codebase to identify deprecated patterns.
   • Prioritize fixes for high-impact rules (e.g., deprecated-reactive).

2. Phase 2: CI Enforcement (1–2 weeks)

   • Add to pull request checks (non-blocking).
   • Document allowed exceptions in filacheck.php.

3. Phase 3: Auto-Fix (Ongoing)

   • Enable --fix for low-risk rules (e.g., action-in-bulk-action-group).
   • Use --backup for critical files.

4. Phase 4: Pro Expansion (Future)

   • Evaluate performance/UX rules for broader adoption.

Operational Impact

Maintenance

• Low Overhead:
  • No runtime impact: Runs only during static analysis (CI/local).
  • Self-updating: Rules improve with Filament releases (e.g., v5 support).
• Configuration Drift:
  • Centralized config: filacheck.php should be version-controlled.
  • Rule updates: Monitor release notes for new deprecations.
• Dependency Management:
  • Update via composer update laraveldaily/filacheck.
  • No breaking changes expected in minor releases.

Support

• Troubleshooting:
  • False positives: Disable rules in config or open issues on GitHub.
  • Auto-fix failures: Use --dry-run to debug.
• Community Resources:
  • GitHub Discussions: Active community for Filament-specific questions.
  • Filament Docs: Linked in error messages (e.g., reactive() → live()).
• SLAs:
  • Critical issues: Escalate to LaravelDaily via GitHub.
  • Pro support: Purchase includes dedicated channels.

Scaling

• Performance:
  • Linear scaling: Rules run in parallel; --dirty reduces scan time.
  • Large codebases: Use directory targeting (e.g., vendor/bin/filacheck app/Filament/Resources).
• Team Adoption:
  • Onboarding: 15-minute tutorial (run --detailed, review output).
  • Training: Highlight top 3 rules causing issues in the codebase.
• Multi-Repo:
  • Monorepos: Run per-package (e.g., filacheck packages/*/Filament).
  • Monolithic: Use --dirty to limit scope.

Failure Modes