Tlint Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Integration: tlint is purpose-built for Laravel, aligning with its opinionated conventions (e.g., facades, controllers, migrations). It leverages Laravel’s ecosystem (e.g., php artisan tlint) and integrates seamlessly with existing tooling (e.g., CI/CD, IDE plugins).
• Modular Design: Linters/formatters are decoupled, allowing selective adoption (e.g., enable only FullyQualifiedFacades or NoDump). This fits well with teams prioritizing incremental codebase improvements.
• AST-Based Analysis: Uses PHP Parser for static analysis, ensuring precision in detecting Laravel-specific patterns (e.g., Blade directives, route paths). Avoids regex-based pitfalls common in generic linters.

Integration Feasibility

• Low Friction: Requires minimal setup (composer require, config file). Compatible with Laravel’s autoloading and service container.
• Preset-Driven: Predefined presets (tighten, laravel) reduce configuration overhead. Custom presets can be defined via tlint.json.
• CLI + Programmatic: Supports both CLI (php artisan tlint) and API usage (e.g., in CI pipelines or IDE hooks). Example:

  $result = (new \Tighten\TLint\TLint())->lint(app_path('Http/Controllers/'));
  

Technical Risk

• False Positives/Negatives:
  • Risk of overzealous linting (e.g., NoDump catching dd() in tests). Mitigate via .tlint.json exclusions or --ignore flags.
  • Blade template linting may conflict with dynamic content (e.g., @if conditions). Test with real-world templates.
• PHP Version Lock-In:
  • Dropped support for PHP 7.3/7.4 (v7.0.0). Ensure project’s PHP version (≥8.1) is compatible.
  • PHP 8.3+ features (e.g., typed properties) may require updates if using newer Laravel versions.
• Dependency Bloat:
  • Underlying duster and php-parser add ~5MB to vendor/. Justify for teams with strict size constraints.

Key Questions

1. Adoption Scope:
   • Will linting be enforced globally (CI blocker) or as a guideline (IDE warnings)?
   • Impact: Affects configuration granularity (e.g., --fix vs. manual fixes).
2. Custom Rules:
   • Are there Laravel-specific conventions not covered (e.g., custom facade aliases, legacy code patterns)?
   • Impact: May require extending TLint or writing custom linters.
3. Performance:
   • How will linting scale for large codebases (e.g., 10K+ files)? Benchmark with --paths config.
   • Impact: CLI timeouts or CI timeouts may necessitate parallelization.
4. Toolchain Integration:
   • Does the team use PHPStan/Psalm? Potential for rule overlap or conflicts.
   • Impact: May need to coordinate linting phases (e.g., run tlint before static analyzers).
5. Maintenance:
   • Who will update tlint versions and resolve breaking changes (e.g., v7.0.0’s PHP version drop)?
   • Impact: Requires a process for dependency updates.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Artisan Integration: Native CLI support via php artisan tlint aligns with Laravel’s workflow.
  • Service Provider: Can be bootstrapped as a service provider for programmatic access:

    $this->app->singleton(\Tighten\TLint\TLint::class, fn() => new \Tighten\TLint\TLint());
    

  • Pint Integration: Works alongside Laravel Pint for formatting (e.g., run tlint before pint).
• CI/CD:
  • Ideal for GitHub Actions/GitLab CI with php artisan tlint --fail-on-errors.
  • Example workflow:

    - name: Lint Code
      run: php artisan tlint --preset=laravel --paths=app,config
    

• IDE/Editor:
  • Supports VS Code/PHPStorm via custom tasks or plugins (e.g., laravel-shift/tlint-vscode).

Migration Path

1. Pilot Phase:
   • Start with a subset of linters (e.g., NoDump, FullyQualifiedFacades) using --only flag.
   • Example:

     php artisan tlint --only=NoDump,FullyQualifiedFacades --paths=app/Http
     

2. Gradual Rollout:
   • Use --fix for auto-correctable issues (e.g., SpacesAroundBladeRenderContent).
   • Example:

     php artisan tlint --preset=tighten --fix
     

3. Configuration Hardening:
   • Customize .tlint.json to exclude legacy paths or adjust severity:

     {
       "presets": ["laravel"],
       "paths": ["app", "config"],
       "ignore": ["app/OldLegacyCode"],
       "severity": {
         "NoDump": "warning"
       }
     }
     

4. CI Enforcement:
   • Fail builds on errors, with warnings for non-critical issues:

     php artisan tlint --fail-on=errors --severity=warning
     

Compatibility

• Laravel Versions:
  • Tested up to Laravel 13.x (v9.6.0). Verify compatibility with your version (e.g., check composer.json constraints).
  • Note: Some linters (e.g., UseAnonymousMigrations) target specific Laravel versions (≥8.37.0).
• PHP Extensions:
  • No hard dependencies beyond PHP core. Ensure php-mbstring is installed for path handling.
• Monorepos/Composers:
  • Supports custom paths (--paths) but may need adjustments for multi-package setups.

Sequencing

1. Pre-Requirements:
   • Update PHP to ≥8.1 (v7.0.0+ requirement).
   • Resolve composer dependency conflicts (e.g., php-parser version).
2. Initial Setup:
   • Install:

     composer require --dev tightenco/tlint
     

   • Publish config (if customizing):

     php artisan vendor:publish --provider="Tighten\TLint\TLintServiceProvider" --tag="tlint-config"
     

3. Testing:
   • Run against a small subset (e.g., app/Http/Controllers) to validate false positives.
   • Example:

     php artisan tlint --preset=laravel --paths=app/Http/Controllers --format=json > lint-results.json
     

4. Iterative Refinement:
   • Adjust presets/rules based on pilot feedback.
   • Example: Disable OneLineBetweenClassVisibilityChanges if team prefers compact classes.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor tlint releases for breaking changes (e.g., v7.0.0’s PHP version drop).
  • Use composer require tightenco/tlint with --update-with-dependencies for minor updates.
• Rule Maintenance:
  • Custom linters/formatters require manual updates if extending TLint.
  • Example: Override a linter in a service provider:

    $this->app->extend(\Tighten\TLint\Linters\NoDump::class, fn() => new CustomNoDumpLinter());
    

• Configuration Drift:
  • Centralize .tlint.json in the repo root to avoid per-developer overrides.
  • Use php artisan tlint:config to generate a baseline config.

Support

• Troubleshooting:
  • Common issues:
    • Path Exclusions: Use --paths to limit scope (e.g., exclude vendor/).
    • Blade Errors: Ignore dynamic Blade files with --ignore=resources/views/*.
    • Performance: Split linting into smaller batches (e.g., by directory).
  • Debug with --verbose or --format=json for machine-readable output.
• Documentation:
  • Leverage the TLint Handbook for advanced usage.
  • Create internal docs for custom presets/rules.
• Community:
  • Active GitHub issues/PRs (526 stars, recent activity). Useful for edge cases (e.g., Blade linting).

Scaling

• Large Codebases:
  • Parallelization: Split paths across CI jobs or use parallel-lint wrappers. Example:

    find app -name "*.php" | xargs -P 4 -I {} php artisan tlint --paths={}
    

  • Incremental Linting: Use