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.

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.

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首次 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.

• No active release since 2023-04-04: Verify compatibility with PHP 8.2/8.3 and latest PHPCS 3.9+. Test in staging first.
  → Extension point: Fork for custom logic (e.g., ignore list via config), but PRs welcomed if upstream is unmaintained.

• 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\...).