Phpcs Import Detection Laravel Package

Getting Started

1. Install via Composer:

   composer require --dev sirbrillig/phpcs-import-detection
   

   Ensure PHP_CodeSniffer (squizlabs/php_codesniffer) is also installed. Note: This package is now tagged with the static-analysis Composer keyword, making it easier to discover via tools like composer why-not or composer why.

2. Configure PHPCS ruleset: In your phpcs.xml (or .phpcs.xml), add the sniff:

   <rule ref="Sirbrillig\ImportDetection\Sniffs\Imports\UnusedUse">
     <severity>5</severity>
   </rule>
   <rule ref="Sirbrillig\ImportDetection\Sniffs\Imports\DuplicateUse">
     <severity>5</severity>
   </rule>
   

   Alternatively, use the provided baseline config:

   <rule ref="Sirbrillig\ImportDetection" />
   

3. Run PHPCS locally or in CI:

   vendor/bin/phpcs --standard=phpcs.xml src/
   

   Issues appear as warnings for unused/duplicate use statements. Note: This release fixes compatibility with PHP 8.2 by addressing deprecated embedded variables in text strings.

Implementation Patterns

• Zero-config adoption: Simply add the rule to your existing ruleset—no extra setup or configuration files needed. Ideal for teams wanting quick hygiene improvements.

• CI enforcement: Embed in GitHub Actions/GitLab CI workflows:

  - name: Run PHPCS with import detection
    run: vendor/bin/phpcs --standard=phpcs.xml --error-severity=5
  

• Gradual onboarding: Start with severity=1 to detect issues non-blockingly, then bump severity to 5 once noise is cleaned.

• Work with PSR-12: Works out-of-the-box alongside PSR12; unused/duplicate imports won’t conflict with style rules.

• Grouped use support: Handles statements like:

  use Foo\Bar\{ClassA, ClassB, ClassC};
  

  and flags unused aliases within the group.

• Integration with IDEs: Most IDEs (e.g., PHPStorm) integrate with PHPCS—fixes appear inline during development.

Gotchas and Tips

• False positives with magic methods / reflection: If your code uses __call(), __get(), or runtime reflection (e.g., Doctrine/ORM), classes imported only via string literals (e.g., for metadata) won’t be detected as used. → Mitigation: Tag such imports with @phpstan-ignore-line or use // @phpcs:ignore Sirbrillig\ImportDetection... on the line.

• Autoloader-only references: Imports used only in string-based class names (e.g., new $className) aren’t detected as used. → Tip: Prefer ::class constants or dependency injection patterns where possible for full coverage.

• Grouped import edge cases: If one alias in a group is unused but others are used, the sniff flags only the unused alias. Ensure PHPCS output highlights per-alias.

• Performance: Scalable to large codebases, but first run on legacy code may surface hundreds of issues. → Pro tip: Use PHPCS diff mode (--report-diff) to auto-fix fixable cases or generate patches.

• PHPCS version incompatibility: Breaking Change: This package does not support newer versions of PHPCS due to issue #52. Ensure your project uses PHPCS 3.8.x or earlier. Check compatibility with:

  vendor/bin/phpcs --version
  

  → Mitigation: Pin PHPCS version in composer.json:

  "require-dev": {
    "squizlabs/php_codesniffer": "^3.8"
  }
  

• Missing autodiscovery: Unlike some sniffs, it does not auto-register. You must explicitly include the rules in your PHPCS config. Double-check for typos in rule names (Sirbrillig\..., not SirBrillig\...).

• PHP 8.2 compatibility: This release fixes issues with deprecated embedded variables in text strings, ensuring compatibility with PHP 8.2 projects.