Filacheck Laravel Package

Getting Started

Run composer require laraveldaily/filacheck --dev in your Filament project. Start with a basic scan of your Filament directory:

vendor/bin/filacheck

For immediate feedback, use --dirty to scan only uncommitted changes:

vendor/bin/filacheck --dirty

Key first-use cases:

1. Pre-commit hook: Add vendor/bin/filacheck --dirty to your pre-commit script to catch issues before merging.
2. CI pipeline: Integrate with GitHub Actions (see example in README) to enforce Filament best practices.
3. AI-generated code validation: Run after generating code with AI tools to validate Filament-specific patterns.

Implementation Patterns

Daily Workflow

1. Pre-commit:

   vendor/bin/filacheck --dirty --fix
   

   Automatically fixes trivial issues (e.g., reactive() → live()) before committing.

2. Post-AI Code Generation:

   vendor/bin/filacheck --dry-run
   

   Preview fixes for AI-generated Filament resources without modifying files.

3. Team Onboarding: Run vendor/bin/filacheck --detailed to explain deprecated patterns to new developers via the output.

Integration Tips

• Laravel Pint Integration: Chain FilaCheck after Pint in CI:

  - run: vendor/bin/pint
  - run: vendor/bin/filacheck
  

• Custom Rules: Extend by publishing the config (php artisan vendor:publish --tag=filacheck-config) and disabling rules like:

  'deprecated-reactive' => ['enabled' => false],
  

• Partial Fixes: Use --fix selectively for rules marked "Partial" (e.g., test methods) by combining with --dry-run first.

Pro Workflow (if using FilaCheck Pro)

1. Performance Audits:

   vendor/bin/filacheck --detailed | grep "Performance"
   

   Identify tables with >10 columns or N+1 query risks in formatStateUsing().

2. Security Sweeps:

   vendor/bin/filacheck --detailed | grep "Security"
   

   Flag missing acceptedFileTypes() or maxSize() in file uploads.

Gotchas and Tips

Pitfalls

1. Config Overrides Ignored:

   • Issue: Disabling rules in config/filacheck.php (e.g., enabled: false) may not work in early versions (<1.1.0). Verify with vendor/bin/filacheck --dry-run.
   • Fix: Update to the latest version or manually patch the rule logic.

2. False Positives in Bulk Actions:

   • Issue: The action-in-bulk-action-group rule may incorrectly flag Action::make() inside toolbarActions() (fixed in v1.1.2).
   • Fix: Update to v1.1.2+ or exclude the rule temporarily.

3. Backup Risks:

   • Issue: --fix --backup creates .bak files but may not handle nested directories cleanly.
   • Fix: Test in a branch or use --dry-run first to preview changes.

4. Windows Paths:

   • Issue: Drive-letter paths (e.g., C:\project) may cause scans to fail.
   • Fix: Use forward slashes (C:/project) or update to v0.3.1+.

Debugging

• Verbose Output: Use --detailed to see rule categories and suppress noise:

  vendor/bin/filacheck --detailed | grep -v "Best Practices"
  

• Rule-Specific Debugging: Isolate a rule by combining with --dry-run:

  vendor/bin/filacheck --dry-run | grep "deprecated-reactive"
  

• Exit Code Handling: In CI, fail builds on non-zero exit codes:

  - run: vendor/bin/filacheck || exit 1
  

Extension Points

1. Custom Rules:

   • Extend the FilaCheck\Rules\Rule class to add project-specific checks (e.g., custom naming conventions).
   • Example: Detect unused Filament widgets in your app.

2. Rule Prioritization:

   • Use the config to enforce critical rules only:

     'deprecated-url-parameters' => ['enabled' => true],
     'deprecated-reactive' => ['enabled' => true],
     // Disable less urgent rules
     'wrong-tab-namespace' => ['enabled' => false],
     

3. Fix Templates:

   • Override fix templates in config/filacheck.php for consistent auto-fixes:

     'fix_templates' => [
         'deprecated-reactive' => '->live()',
     ],
     

Pro Tips

• Git Blame Integration: Combine with git blame to track who introduced deprecated patterns:

  vendor/bin/filacheck --detailed | awk '/Line/ {print $2}' | xargs -I{} git blame {} -L{},{}
  

• Exclude Directories: Use --path to skip tests or legacy code:

  vendor/bin/filacheck --path="app/Filament/Resources --exclude=app/Filament/Tests"
  

• Performance: For large projects, scan incrementally:

  vendor/bin/filacheck --path="app/Filament/Resources/Pages"
  vendor/bin/filacheck --path="app/Filament/Resources/Widgets"