Tlint Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev tightenco/tlint
   

   Add to composer.json under require-dev:

   "tightenco/tlint": "^9.6"
   

2. Configuration: Create tlint.json in your project root:

   {
     "presets": ["tighten"],
     "paths": ["app", "config", "routes"]
   }
   

3. First Run:

   vendor/bin/tlint
   

   This runs all linters in the tighten preset against specified paths.

First Use Case

Run TLint as a pre-commit hook to enforce conventions before code is committed:

# Add to package.json (if using npm scripts)
"scripts": {
  "lint": "tlint"
}

Or integrate with Git hooks (e.g., husky):

npx husky add .husky/pre-commit "vendor/bin/tlint"

Implementation Patterns

Workflows

1. Daily Linting: Run TLint in CI/CD pipelines (e.g., GitHub Actions) to catch violations early:

   # .github/workflows/lint.yml
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: vendor/bin/tlint
   

2. Selective Linting: Target specific linters or files:

   # Run only the `FullyQualifiedFacades` linter
   vendor/bin/tlint --only FullyQualifiedFacades
   
   # Lint a single file
   vendor/bin/tlint app/Http/Controllers/UserController.php
   

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

   {
     "presets": ["tighten"],
     "linters": {
       "NoDump": {
         "enabled": true,
         "allow": ["dd", "dump", "ray"]
       }
     }
   }
   

4. Formatter Integration: Use formatters to auto-fix issues (e.g., FullyQualifiedFacades):

   vendor/bin/tlint --format
   

Integration Tips

• Laravel IDE Helper: Combine with barryvdh/laravel-ide-helper to auto-generate facades for FullyQualifiedFacades.
• PHPStorm: Configure TLint as an external tool:
  • File: vendor/bin/tlint
  • Arguments: --format $FilePath$
  • Working Directory: $ProjectFileDir$
• VSCode: Use the PHP Intelephense extension with TLint’s checkstyle output:

  // .tlint.json
  {
    "reporting": {
      "checkstyle": true
    }
  }
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • NoDump linter may flag dd() or dump() calls. Exclude them in config:

     "linters": {
       "NoDump": {
         "allow": ["dd", "dump"]
       }
     }
     

   • OneLineBetweenClassVisibilityChanges may fail with complex comments. Use --ignore to skip files:

     vendor/bin/tlint --ignore app/Models/ComplexModel.php
     

2. Performance:

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

     "paths": ["app", "config"],
     "ignore": ["**/tests/**", "**/storage/**"]
     

   • Run TLint in parallel (if supported by your CI):

     vendor/bin/tlint --parallel
     

3. Breaking Changes:

   • v7.0.0+: Removed redundant linters (e.g., AlphabeticalImports). Update your config if relying on them.
   • v9.0.0+: Dropped tformat.json in favor of tlint.json. Merge configs if upgrading.

Debugging

• Verbose Output:

  vendor/bin/tlint -v
  

  Reveals skipped files and linter details.

• Dry Run:

  vendor/bin/tlint --dry-run
  

  Shows what would be fixed without modifying files.

Extension Points

1. Custom Linters: Extend Tighten\TLint\Linter to create reusable linters:

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

   Register in tlint.json:

   "linters": {
     "CustomLinter": {
       "class": "App\\TLint\\CustomLinter"
     }
   }
   

2. Formatter Overrides: Override default formatters (e.g., FullyQualifiedFacades) by extending Tighten\TLint\Formatter:

   namespace App\TLint;
   
   use Tighten\TLint\Formatter;
   
   class CustomFacadeFormatter extends Formatter {
       public function format($node) {
           // Custom logic
       }
   }
   

3. Reporting: Generate custom reports (e.g., JUnit for CI):

   "reporting": {
     "checkstyle": true,
     "output": "build/report.xml"
   }
   

Pro Tips

• Laravel-Specific: Use FullyQualifiedFacades to enforce use Illuminate\Support\Facades\Log; instead of use Log;.
• Blade Files: TLint supports Blade linting (e.g., SpaceAfterBladeDirectives). Add Blade paths:

  "paths": ["resources/views"]
  

• CI Feedback: Fail builds on lint errors:

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