Filacheck Laravel Package

Technical Evaluation

Architecture Fit

• Highly specialized for Filament v4/v5: The package is tightly coupled with Filament’s API, making it an ideal fit for projects using Filament as their admin panel framework. It leverages Filament’s evolving patterns (e.g., reactive() → live(), form() → schema()) to enforce consistency and reduce technical debt.
• Static analysis tooling: Mimics tools like Laravel Pint or PHP-CS-Fixer but focuses on domain-specific rules (e.g., deprecated Filament methods, UX/performance warnings). Integrates seamlessly into existing static analysis pipelines.
• Rule-based architecture: Modular design allows for easy extension (e.g., adding custom rules or disabling existing ones via config). The 16 free rules cover critical deprecations, while Pro adds performance/security/UX checks.

Integration Feasibility

• Laravel/PHP ecosystem compatibility: Built as a Composer package with CLI integration (vendor/bin/filacheck), requiring no framework-level changes. Works alongside existing tools like Pint, Pest, or Laravel’s built-in testing.
• Filament-specific dependencies: Relies on Filament’s class structure (e.g., Filament\Schemas\Components\Tabs\Tab), so integration is limited to Filament projects. Non-Filament Laravel apps will see no benefit.
• CI/CD readiness: Designed for pipeline integration (exit codes 0/1 for pass/fail), with GitHub Actions example provided. Can run in parallel with other checks (e.g., tests, linting).

Technical Risk

• False positives/negatives: Early-stage auto-fix features (e.g., --fix) may introduce edge cases. Rule deprecated-test-methods is marked "Partial," suggesting incomplete coverage.
• Filament version lock-in: Rules target v4/v5 specifically; migration to v6+ may require rule updates. No backward compatibility guarantees for older Filament versions.
• Performance overhead: Scanning large Filament codebases could slow CI pipelines. The --dirty flag mitigates this for uncommitted changes.
• Configuration complexity: Per-rule enable/disable requires publishing config (php artisan vendor:publish), adding minor setup friction.

Key Questions

1. Filament version alignment: Does the project use Filament v4/v5? If not, is there a plan to upgrade?
2. CI pipeline impact: How will FilaCheck’s runtime compare to existing checks (e.g., PHPStan, Pest)? Should it run in a separate job or merged with linting?
3. Auto-fix adoption: Given the --fix feature is beta, should it be enabled in CI (risk of unintended changes) or reserved for local dev?
4. Pro vs. Free: Are the Pro rules (performance/security/UX) critical for the project’s goals? If so, budget for licensing must be considered.
5. Custom rules: Are there Filament-specific patterns in the codebase not covered by FilaCheck’s rules? If yes, could they be contributed or extended?
6. Team adoption: Will developers treat FilaCheck warnings as actionable (e.g., fixing deprecations) or as noise? Success depends on clear communication of its value.

Integration Approach

Stack Fit

• Primary use case: Filament-based admin panels (Resources, Pages, Widgets, Actions).
• Secondary use case: Post-AI code generation (e.g., GitHub Copilot) to catch Filament-specific anti-patterns.
• Toolchain compatibility:
  • CI/CD: Integrates with GitHub Actions, GitLab CI, or CircleCI via Composer. Can replace or supplement php-cs-fixer/pint for Filament-specific checks.
  • Local dev: Run manually (vendor/bin/filacheck) or via IDE hooks (e.g., PHPStorm’s "Before Commit" scripts).
  • Pre-commit: Use tools like Laravel Git or Husky to run --dirty checks before commits.
• Dependencies:
  • Requires PHP 8.1+ (implied by Filament v4/v5 support).
  • No database or server requirements (pure static analysis).

Migration Path

1. Installation:

   composer require laraveldaily/filacheck --dev
   

   • Add to composer.json under require-dev to exclude from production.
2. Configuration (optional):
   • Publish config to disable rules:

     php artisan vendor:publish --tag=filacheck-config
     

   • Example: Disable deprecated-reactive if migrating incrementally.
3. CI Integration:
   • Add to .github/workflows/ci.yml (example provided in README).
   • Start with --dirty mode to avoid scanning the entire codebase initially.
4. Local Workflow:
   • Add to package.json scripts (if using npm):

     "scripts": {
       "check:filament": "php vendor/bin/filacheck --dirty"
     }
     

   • Or use a Makefile target:

     check-filament:
         php vendor/bin/filacheck --dirty
     

Compatibility

• Filament versions: Tested on v4/v5. For v6+, validate if rules remain relevant (e.g., new deprecations may emerge).
• Monorepos: Supports scanning specific directories (e.g., app/Filament/Resources). Useful for large codebases with multiple Filament instances.
• Windows/Linux/macOS: Cross-platform support confirmed (fixes for Windows paths in v0.3.1).
• Docker/Sail: Compatible (Sail support added in v1.2.3).

Sequencing

1. Initial adoption:
   • Run in CI with --dirty to identify issues in uncommitted changes.
   • Use --dry-run to preview fixes before enabling --fix.
2. Gradual enforcement:
   • Start with non-blocking warnings (exit code 1 but not failing CI).
   • Transition to blocking (fail CI on warnings) after addressing critical issues.
3. Pro rules:
   • Evaluate Pro rules separately (e.g., performance/security) with a phased rollout.
4. Auto-fix:
   • Enable --fix locally first, then in CI after validating safety (e.g., via backup files --backup).

Operational Impact

Maintenance

• Rule updates: FilaCheck requires updates to stay aligned with Filament’s evolving API. Monitor Filament releases and FilaCheck changelogs for new deprecations.
• Configuration drift: Disabling rules via config may need revisiting as Filament evolves. Document rationale for disabled rules.
• Dependency management: Like other dev tools, ensure it’s updated alongside Filament and PHP versions.

Support

• Troubleshooting:
  • False positives: Review rule descriptions and Filament docs. Contribute fixes if needed.
  • Performance: For large codebases, limit scans to app/Filament or use --dirty.
  • Auto-fix issues: Test fixes locally before enabling in CI; use --backup for safety.
• Community: Active GitHub repo with responsive maintainers (120+ stars, recent releases). Pro support available via filamentexamples.com.
• Documentation: README is comprehensive, but Pro rules lack free documentation. Clarify expectations for Pro features if adopted.

Scaling

• Codebase size: Performance scales linearly with Filament code. For 10K+ LoC, consider:
  • Running in parallel with other checks.
  • Excluding non-Filament directories (e.g., app/Http).
• Team size: Effective for teams >2 using Filament. Smaller teams may find manual reviews sufficient.
• Multi-repo: Reusable via Composer, but config must be replicated per repo.

Failure Modes

Ramp-Up

• Onboarding:
  • For developers: Run vendor/bin/filacheck --detailed locally to understand warnings. Pair with Filament docs for context.
  • For PMs: Highlight how FilaCheck reduces long-term maintenance (e.g., "This warning saves 2 hours of debugging later").
• Training:
  • Add a section to the team’s coding guidelines explaining FilaCheck’s purpose and rules.