Tlint Laravel Package

Getting Started

Start by installing tightenco/tlint via Composer and running the CLI to see what’s flagged in your project:

composer require --dev tightenco/tlint
./vendor/bin/tlint check

The default behavior uses the Tighten preset (a curated set of Laravel-specific rules like NoDump, FullyQualifiedFacades, UseAnonymousMigrations, etc.). The output highlights issues with file paths and line numbers—ideal for catching anti-patterns before code review. For your first foray, try applying auto-fixes for safe rules:

./vendor/bin/tlint fix

Check tlint.json in your project root to see the current config (or run ./vendor/bin/tlint init to generate one).

Implementation Patterns

• CI Integration: Add ./vendor/bin/tlint check --preset Laravel to your GitHub Actions or GitLab CI workflow. Use the --format checkstyle option to produce machine-readable reports for review tools.
• Per-File Customization: Use paths in tlint.json to limit checks to app/, database/, or tests/—especially helpful in monorepos or legacy apps with mixed styles.
• Rule Selection: Instead of a preset, pick rules explicitly in tlint.json:

  {
    "rules": ["NoDump", "NoRequestAll", "UseAnonymousMigrations"]
  }
  

• Blade & Migrations: Leverage blade-specific formatters (e.g., SpaceAfterBladeDirectives, RemoveLeadingSlashNamespaces) to enforce consistent @extends, @inject, and route definitions—common pain points in Laravel codebases.
• Custom Linters: Extend Linter and Formatter base classes to enforce team-specific rules (e.g., banning view() in controllers, enforcing named scopes). Register via config/tlint.php or a config file.

Gotchas and Tips

• PHP Version: v7+ requires PHP 8.0+. Use ^6.x for older codebases on PHP 7.4. Check composer.json compatibility before upgrading.
• --only Limitation: In v6.2.0+, --only works for all rules—even custom ones—but it’s case-sensitive and expects exact rule names (e.g., NoDump, not nodump). Run tlint list to verify available rules.
• Blade Quirks: The SpacesAroundBladeRenderContent rule ignores escaped blade ({{ '{' }}) to avoid false positives. Similarly, FullyQualifiedFacades in Blade files now allows @inject('foo', Foo::class)—watch for edge cases in custom directives.
• Auto-Fix Caution: Not all issues are auto-fixable. Use --dry-run to preview changes before committing. Always commit composer.lock and tlint.json to avoid divergent behavior across environments.
• Performance Tip: Use paths to avoid scanning storage/, vendor/, or test fixtures unnecessarily. For large repos, run tlint check app/ instead of full-project scans during development.
• Troubleshooting: If linters ignore a file, check if it’s matched by default excludes (e.g., vendor/, storage/). Override with explicit paths or use --include-path for debugging.