Phpcompatibility Paragonie Laravel Package

Getting Started

1. Install the package as a dev dependency:

   composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
   composer require --dev phpcompatibility/phpcompatibility-paragonie:"^2.0@dev"
   

   The Composer PHPCS plugin automatically registers the standards — verify via vendor/bin/phpcs -i.

2. First use case: If your project uses paragonie/sodium_compat (or random_compat), run static analysis to catch false positives from the generic PHPCompatibility standard:

   vendor/bin/phpcs src/ --standard=PHPCompatibilityParagonieSodiumCompat --runtime-set testVersion 7.2-
   

3. Start with --standard=PHPCompatibilityParagonieSodiumCompat if using sodium_compat (it auto-includes random_compat rules); otherwise use PHPCompatibilityParagonieRandomCompat if only using random_compat.

Implementation Patterns

• Include in CI: Add the appropriate standard to your CI pipeline (e.g., GitHub Actions, GitLab CI):

  - vendor/bin/phpcs src/ --standard=PHPCompatibilityParagonieSodiumCompat --runtime-set testVersion 8.1- --extensions=php
  

• Project-level configuration: Extend in phpcs.xml.dist:

  <config name="testVersion" value="7.4-"/>
  <rule ref="PHPCompatibilityParagonieSodiumCompat"/>
  

• Use with PHPCompatibility: This package complements — not replaces — the core PHPCompatibility standard. If not already using it, add both:

  vendor/bin/phpcs src/ --standard=PHPCompatibility,PHPCompatibilityParagonieSodiumCompat --runtime-set testVersion 7.4-
  

• Custom exclusions: Avoid blanket // phpcs:ignore — instead, rely on the rulesets to suppress known polyfill usage. Only add inline ignores for false positives caused by upstream polyfill changes (monitor changelog).

Gotchas and Tips

• Conflicting Composer plugins: If you manually manage installed_paths or use another PHPCS plugin (e.g., squizlabs/php_codesniffer with custom paths), remove those — the Composer PHPCS plugin now handles autoregistration.

• Upgrade bumps may break exclusions: PHPCompatibility 10.x changes sniff codes (e.g., PHPCompatibility.FunctionUse.RemovedFunctions). After upgrading phpcompatibility-paragonie, review changelogs and update custom <exclude> rules or // phpcs:ignore PHPCompatibility annotations with new codes.

• False negatives: If your project does not use Paragonie polyfills but references PHP polyfill functions (e.g., random_int()), using these rulesets will not flag issues — ensure you also scan with the base PHPCompatibility standard.

• Testing the polyfill itself: The rulesets include special handling to avoid reporting issues in polyfill source code (e.g., vendor/paragonie/sodium_compat/). Do not point sniffing at vendor/ — run only on src/.

• Maturity & maintenance: Last release is dated 2025-11-29 (future-dated — likely a placeholder or test data), but commit history and changelog show active maintenance. Monitor for updates when sodium_compat/random_compat introduce breaking changes.