Php Compatibility Laravel Package

Getting Started

1. Install via Composer in your project’s root:

   composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
   composer require --dev phpcompatibility/php-compatibility:^10.0
   

   The dealerdirect/phpcodesniffer-composer-installer plugin auto-registers the standard with PHPCS.

2. Verify installation by running:

   vendor/bin/phpcs -i
   

   Confirm PHPCompatibility appears in the list of installed standards.

3. First use case: Run basic checks for deprecated/removed PHP features (without specifying version):

   vendor/bin/phpcs -ps src/ --standard=PHPCompatibility
   

   To get actionable compatibility reports (e.g., usage of new syntax/features), specify target PHP version(s):

   vendor/bin/phpcs src/ --standard=PHPCompatibility --runtime-set testVersion 8.1-
   

Implementation Patterns

• CI/CD Integration: Add PHPCompatibility to your pipeline (e.g., GitHub Actions, GitLab CI) before test execution:

  - name: Run PHPCompatibility checks
    run: vendor/bin/phpcs src/ tests/ --standard=PHPCompatibility --runtime-set testVersion 8.2-
  

• Custom Ruleset with testVersion: Define your minimum PHP version per project in phpcs.xml:

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

  This avoids repeating --runtime-set testVersion on every CLI call.

• Framework-specific rulesets: If using WordPress, Joomla, or Symfony, install and extend their dedicated standards (e.g., PHPCompatibilityWP) in addition to PHPCompatibility, and always pair with explicit testVersion.

• Per-file overrides: In CI, run separate checks for bootstrap files targeting older PHP versions:

  vendor/bin/phpcs bootstrap.php --standard=PHPCompatibility --runtime-set testVersion 5.6-
  

• IDE Integration: Configure your editor (VS Code, PHPStorm) to use vendor/bin/phpcs as the PHPCS executable and set "phpcs.standard": "PHPCompatibility" in workspace settings.

Gotchas and Tips

• testVersion precedence: CLI --runtime-set testVersion overrides ruleset <config>. Use CLI to override for edge cases (e.g., legacy bootstrap files) but prefer ruleset defaults for consistency.

• Removed extension false positives: Sniff PHPCompatibility.Extensions.RemovedExtensions may flag userland functions (e.g., mysql_*) that aren’t native. Whitelist safe functions in your ruleset:

  <rule ref="PHPCompatibility.Extensions.RemovedExtensions">
      <properties>
          <property name="functionWhitelist" type="array">
              <element value="my_custom_mysql_helper"/>
          </property>
      </properties>
  </rule>
  

• Serializable interface tracking: Sniff PHPCompatibility.Interfaces.RemovedSerializable relies on awareness of custom Serializable-extending interfaces. Add project-specific ones via:

  <rule ref="PHPCompatibility.Interfaces.RemovedSerializable">
      <properties>
          <property name="serializableInterfaces" type="array">
              <element value="App\Interfaces\MySerializableInterface"/>
          </property>
      </properties>
  </rule>
  

• Version range gotchas: Avoid ranges like 8.0-8.3 if your project targets deployment on future PHP versions. Prefer 8.0- or 8.2- unless targeting exact e.g. LTS releases.

• Performance tip: Limit sniffing scope to src/ and tests/—exclude dependencies (e.g., vendor/) with <exclude-pattern> to avoid PHPCS overhead.

• Keep dependencies updated: PHPCompatibility receives new sniffs per PHP release. Update frequently, especially around new PHP versions (e.g., before upgrading from 8.2 → 8.3):

  composer update phpcompatibility/php-compatibility --with-dependencies
  

• Debugging: Use -vv to see which sniffs fired. Cross-check PHPCS output with PHP manual deprecation/changes to validate false/negatives.