Phpinsights Laravel Package

Getting Started

Start by installing the package via Composer (require-dev):

composer require nunomaduro/phpinsights --dev

Run it immediately with ./vendor/bin/phpinsights — no config needed. It scans app/, config/, routes/, and database/ by default, producing a summary score and breaking issues into categories: Architecture, Complexity, Distribution, Style, and Code (e.g., NestingLevel, CognitiveComplexity, UnusedCode). First use case: run before merging PRs or during local development to get instant feedback on newly added code.
v2.14.0 note: Fully supports Laravel 13 and Symfony 8, making it ideal for projects upgrading to latest major releases. PHP 8.5 is now supported (including new language features and deprecation changes), while support for PHP 8.1/8.2 has been dropped — ensure your CI/development environment uses PHP 8.3 or 8.5.

Implementation Patterns

Integrate into your workflow using presets, CLI flags, and CI automation.

• Use --preset=[laravel|symfony|wordpress] to adapt rules to framework conventions (e.g., --preset=laravel enforces service container best practices).
• Set custom thresholds via phpinsights.php config file (generated on first run via ./vendor/bin/phpinsights --init), allowing team-specific tolerance for complexity or style violations.
• Run in CI (GitHub Actions, GitLab CI) with exit codes: phpinsights --min-quality=80 --min-complexity=60 --min-architecture=70 to fail builds when thresholds drop below.
• Use --format=json or --format=checkstyle for integration with tools like SonarQube or GitHub Code Scanning.
• Leverage the --debug flag during refactoring to trace exactly which rule triggered a comment (e.g., "CognitiveComplexity too high in App\Services\OrderProcessor::calculateTotal()").
  v2.14.0 note: When upgrading to Laravel 13, use --preset=laravel — the preset now includes rules aligned with Laravel 13’s syntax and conventions (e.g., updated enum usage, new event listener patterns). Similarly, Symfony 8 features (e.g., improved attributes handling) are validated under --preset=symfony.

Gotchas and Tips

• Stale scan cache: PHPInsights caches results per-file; clear with --clear-cache if changes aren’t reflected.
• Laravel-specific quirks: Rules like ForbiddenImplicitCatchBlock may flag try {} catch (\Exception $e) {} blocks — explicitly declare Throwable if handling both Error and Exception.
• Config precedence: phpinsights.php config overrides defaults, but CLI flags override the config — double-check order of precedence.
• Hotspots overload: The report highlights “hotspots” by default; for focused reviews, use --only=Architecture,Style to narrow scope.
• Ignoring files/folders: Use phpinsights.php's exclude array (not .phpinsightsignore) — the latter is not supported.
• Extensibility: Add custom rules by extending PHP_CodeSniffer\Sniffs\Sniff and registering via phpinsights.php → settings → sniffs — but note this package is not PHPCS itself; custom rules must integrate via PHP Insights’ own sniff infrastructure.
• PHP version requirement: As of v2.14.0, PHP 8.3 or higher is required. Running on PHP 8.0 or lower will cause fatal errors; CI pipelines must explicitly use PHP ≥8.3.