Tlint Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Integration: tlint is purpose-built for Laravel, aligning with its ecosystem (e.g., presets for Laravel conventions like FullyQualifiedFacades, UseAnonymousMigrations, and RequestValidation). This reduces friction in adoption and ensures consistency with Laravel’s evolving standards (e.g., Laravel 11/13 compatibility in v9.x).
• Modular Design: The package leverages a linter/formatter separation, allowing granular control over enforcement (e.g., --only flag for targeted checks). This fits well with modern CI/CD pipelines where incremental linting is preferred.
• AST-Based Analysis: Built on PHP Parser, it enables deep code analysis (e.g., detecting dd()/dump() calls, blade directive spacing) without regex limitations. This is critical for enforcing complex Laravel patterns (e.g., facades, route paths).

Integration Feasibility

• Low Barrier to Entry: Requires only composer require tightenco/tlint and minimal config (tlint.json). No database migrations or service provider bindings are needed.
• CLI-Driven: Designed for pre-commit hooks (via tlint:fix) or CI pipelines (e.g., GitHub Actions). Example:

  ./vendor/bin/tlint --fix --preset=laravel
  

• Symfony/Process Compatibility: Uses Symfony’s Process component for cross-platform execution (Windows/Linux/macOS), reducing environment-specific issues.

Technical Risk

• Deprecation Risk:
  • PHP 7.3/7.4 Dropped in v7.0.0. If the codebase uses these versions, a migration to PHP 8.1+ is required (see PHP Upgrade Guide).
  • Removed Linters: Some linters (e.g., NoCompact, NoDump) were deprecated. Ensure replacements (e.g., @ray detection in v9.5.0) meet team needs.
• False Positives/Negatives:
  • Blade template linting (e.g., SpacesAroundBladeRenderContent) may conflict with custom directives. Test edge cases like @inject or @stack.
  • Dynamic Method Calls: Fixed in v9.6.1, but legacy code using __call() or magic methods may still trigger issues.
• Performance:
  • AST parsing can be CPU-intensive for large codebases. Benchmark with tlint --profile to identify bottlenecks (e.g., nested facades, complex route files).

Key Questions

1. Convention Alignment:
   • Does the team’s Laravel style guide align with tlint’s presets (e.g., FullyQualifiedFacades, UseAnonymousMigrations)? If not, custom presets may be needed.
2. CI/CD Impact:
   • How will linting be gated? Pre-commit (e.g., Husky) or CI-only? Example GitHub Actions workflow:

     - name: Run TLint
       run: ./vendor/bin/tlint --preset=laravel --fail-on=warning
     

3. Formatter vs. Linter:
   • Should tlint:fix auto-correct issues (e.g., SpaceAfterBladeDirectives) or only report them? Balance developer productivity vs. merge conflicts.
4. Excluded Paths:
   • Will certain directories (e.g., tests/, vendor/) be excluded? Use the paths config option:

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

5. Legacy Code:
   • How will existing violations (e.g., dd() calls, unqualified facades) be addressed? A phased rollout with --ignore flags may be needed.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Ideal for: Laravel 8.0+ projects using modern conventions (e.g., facades, anonymous migrations, Vite).
  • Less Ideal for: Legacy Laravel (pre-8.0) or non-Laravel PHP projects (though generic PHP linting is possible).
• Toolchain Compatibility:
  • PHPStan/Psalm: Can complement static analysis (e.g., tlint for style, PHPStan for logic).
  • PHP-CS-Fixer: Overlap exists (e.g., SpacesAroundBladeRenderContent), but tlint focuses on Laravel-specific rules.
  • Editor Plugins: Supports VS Code via php-cs-fixer integration or custom tasks.

Migration Path

1. Pilot Phase:
   • Run tlint in dry mode to assess violations:

     ./vendor/bin/tlint --preset=laravel --format=checkstyle > tlint.xml
     

   • Use tlint.json to customize excluded paths/rules:

     {
       "presets": ["laravel"],
       "exclude": ["app/Helpers/*.php"],
       "rules": {
         "NoDump": "error",
         "FullyQualifiedFacades": "warning"
       }
     }
     

2. Incremental Enforcement:
   • Start with --fix for auto-correctable issues (e.g., blade spacing).
   • Gate critical linters (e.g., NoDump) in CI with --fail-on=error.
3. Legacy Handling:
   • Use --ignore for temporary exclusions:

     ./vendor/bin/tlint --ignore="app/OldCode/*.php"
     

   • Gradually refactor excluded code to meet standards.

Compatibility

• PHP Versions:
  • Supported: 8.1–8.3 (as of v9.6.1). Drop PHP 7.x support if using v7.0.0+.
  • Testing: Add to CI matrix:

    services:
      php81: "8.1"
      php82: "8.2"
      php83: "8.3"
    

• Laravel Versions:
  • Tested up to Laravel 13.x (v9.6.0). Verify compatibility with custom packages (e.g., spatie/laravel-permission).
• Dependency Conflicts:
  • Check for version clashes with php-parser or symfony/process (e.g., Laravel’s illuminate/support may bundle similar components).

Sequencing

1. Pre-Requirements:
   • Ensure PHP ≥8.1 and Laravel ≥8.0 (or patch legacy code).
   • Install dependencies:

     composer require --dev tightenco/tlint php-cs-fixer
     

2. Configuration:
   • Generate tlint.json:

     ./vendor/bin/tlint --init
     

   • Customize presets/rules based on team standards.
3. Tooling Setup:
   • Add to composer.json scripts:

     "scripts": {
       "lint": "tlint --preset=laravel",
       "lint:fix": "tlint --fix"
     }
     

   • Integrate with Husky for pre-commit:

     {
       "husky": {
         "hooks": {
           "pre-commit": "composer lint"
         }
       }
     }
     

4. CI Pipeline:
   • Add to .github/workflows/lint.yml:

     - name: TLint
       run: composer lint
     

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: Custom tlint.json may diverge from upstream presets. Mitigate by:
    • Using extends to inherit presets:

      {
        "extends": ["tighten"],
        "rules": { ... }
      }
      

    • Regularly updating dependencies (composer update tightenco/tlint).
• Rule Updates:
  • Monitor changelogs for breaking changes (e.g., v7.0.0’s PHP version drop). Example:

    composer why-not tightenco/tlint@7.0.0
    

• Dependency Updates:
  • php-parser and symfony/process may require updates. Test with:

    ./vendor/bin/tlint --profile
    

Support

• Troubleshooting:
  • False Positives: Use --debug to inspect AST nodes:

    ./vendor/bin/tlint --debug --only=NoDump
    

  • Blade Issues: Exclude custom directives via tlint.json:

    {
      "blade": {
        "ignoredDirectives": ["@custom"]
      }
    }
    

  • Performance: Optimize by excluding large files (e.g., database/migrations/).
• Community Resources:
  • GitHub Discussions: tighten/tlint.
  • Laravel Slack: #code-quality channel.
• Custom Rules: