Type Coverage Laravel Package

Getting Started

Install via Composer: composer require --dev tomasvotruba/type-coverage. Run vendor/bin/type-coverage on your project root to get an immediate report. The CLI output shows total type coverage % and breaks it down by type of element (parameter, return, property), highlighting specific files with gaps. Start by scanning a single subdirectory (e.g., src/Service) to isolate a small scope—ideal for pilot adoption. Check the generated JSON report (--output-format=json) to integrate with dashboards or CI dashboards.

Implementation Patterns

• Gradual Rollout: Begin with --min-te coverage 70% to fail builds only if coverage drops below 70%, while running without enforcement during initial phase to gather data. Gradually raise the threshold (75% → 80% → …) as teams improve.
• CI Integration: Add to composer.json scripts ("type-coverage": "type-coverage --min-coverage 85%") and call it in CI before static analysis steps. Failures are human-readable and point to exact file/line.
• Path Filtering: Use --path src/Domain to focus only on business-critical layers, ignoring tests or generated code (e.g., --exclude-path tests).
• Historical Tracking: Pipe --format=csv output to a log file or DB to track coverage trends per release. Combine with git log --oneline to tie coverage changes to PRs.
• Pre-commit Hook (Optional): Run type-coverage --min-coverage 90% --changed-since=HEAD~1 to enforce type coverage only for diff—ideal for legacy repos where full baseline would be overwhelming.

Gotchas and Tips

• False Negatives in Trait Methods: If a class uses traits, type coverage may report traits as untyped even when the consuming class has strict types—verify reported lines manually.
• Config via type-coverage.neon: While CLI flags work, define thresholds and exclusions in a config file to avoid repetition:

  parameters:
      minCoverage: 85
      paths: [src]
      excludePaths: [tests, src/Generated]
      focusOn: [parameter, return]
  

• Focus-first Strategy: Use --sort=least-covered to surface worst offenders first. Tackle one file at a time—fixing type coverage is more sustainable than bulk fixes.
• PHPStan Conflicts: If using PHPStan, avoid overlapping analysis by disabling generic parameter/return rules (parameters: true → parameters: false in PHPStan config) to prevent duplicate warnings.
• Static Analysis Blind Spots: This package only checks explicit types. It won’t catch nullable bugs (e.g., missing ? on return types), so combine with phpstan/phpstan or shipmonk/composer-change-detector for full type safety.