Tlint Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev tightenco/tlint
   

   Add to composer.json under require-dev:

   "tightenco/tlint": "^9.0"
   

2. Configuration: Create tlint.json in your project root with a basic preset:

   {
     "presets": ["tighten"]
   }
   

3. First Run:

   vendor/bin/tlint
   

   This runs the default Tighten preset against all PHP files.

First Use Case

Onboarding a new developer: Run vendor/bin/tlint to enforce Laravel conventions (e.g., facades, class ordering, Blade spacing) and auto-fix common issues with --fix.

Implementation Patterns

Workflow Integration

1. CI/CD Hook: Add to .github/workflows/lint.yml:

   - name: Run TLint
     run: vendor/bin/tlint --fix
   

   Fail builds on violations unless --fix resolves them.

2. Pre-Commit Hook: Use husky or pre-commit to run TLint on staged files:

   vendor/bin/tlint --paths="app/Http/Controllers/**/*.php"
   

3. Custom Presets: Extend the default preset in tlint.json:

   {
     "presets": ["tighten", "laravel"],
     "linters": ["NoDump", "FullyQualifiedFacades"],
     "formatters": ["ArrayParametersOverViewWith"]
   }
   

Common Patterns

• Auto-Fix Common Issues:

  vendor/bin/tlint --fix --only="FullyQualifiedFacades,NoDump"
  

• Target Specific Paths:

  vendor/bin/tlint --paths="app/Models,app/Providers"
  

• Checkstyle Output for CI:

  vendor/bin/tlint --report=checkstyle > tlint-results.xml
  

IDE Integration

• PHPStorm: Add vendor/bin/tlint as an external tool with:

  Program: $ProjectFileDir$/vendor/bin/tlint
  Arguments: --paths=$FilePathRelativeToProjectRoot$
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • NoDump linter flags @dd, @dump, and ray(). Exclude these in tlint.json:

     {
       "linters": {
         "NoDump": {
           "ignore": ["@dd", "@dump", "ray"]
         }
       }
     }
     

   • OneLineBetweenClassVisibilityChanges may fail with docblocks. Use --fix to resolve.

2. Performance:

   • Exclude large directories (e.g., vendor/, storage/) in tlint.json:

     {
       "paths": ["app/", "config/", "routes/"]
     }
     

   • Run TLint incrementally during development:

     vendor/bin/tlint --paths="app/Http/Controllers/$FILE.php"
     

3. Breaking Changes:

   • v7.0.0: Removed redundant linters (e.g., NoCompact, UseConfigOverEnv). Update your config if using custom rules.
   • v9.0.0: Merged tformat.json into tlint.json. Migrate old configs.

Debugging

• Verbose Output:

  vendor/bin/tlint -v
  

• Dry Run:

  vendor/bin/tlint --dry-run
  

• Skip Cache:

  vendor/bin/tlint --no-cache
  

Extension Points

1. Custom Linters/Formatters: Extend Tighten\TLint\Linter or Tighten\TLint\Formatter:

   namespace App\TLint;
   
   use Tighten\TLint\Linter;
   
   class CustomLinter extends Linter {
       protected $message = 'Custom rule: {{message}}';
       public function lint($node) {
           // Custom logic
       }
   }
   

   Register in tlint.json:

   {
     "linters": ["App\\TLint\\CustomLinter"]
   }
   

2. Preset Overrides: Override default presets by redefining them:

   {
     "presets": [],
     "linters": ["tighten:NoDump", "tighten:FullyQualifiedFacades"]
   }
   

Pro Tips

• Laravel-Specific Rules:
  • Enforce FullyQualifiedFacades to avoid use Auth; in favor of use Illuminate\Support\Facades\Auth;.
  • Use RequestValidation formatter to move validation logic from controllers to Form Requests.
• Blade Files: TLint supports Blade files for spacing (SpacesAroundBladeRenderContent) and directives (SpaceAfterBladeDirectives).
• Windows Compatibility: Use --no-windows flag if encountering path issues:

  vendor/bin/tlint --no-windows