Codesniffer Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package extends PHP_CodeSniffer (a static analysis tool) to enforce PSR-2 with additional custom rules. It fits well in a Laravel/PHP ecosystem where code quality, consistency, and maintainability are priorities.

  • Use Cases:
    • Pre-commit hooks (via Git hooks or Laravel Forge/Envoyer).
    • CI/CD pipelines (e.g., GitHub Actions, GitLab CI, Laravel Pint/Parallel Lint).
    • Local development (via PHPStorm/VSCode integration or CLI).
  • Non-Fit: If the team already uses a stricter standard (e.g., PSR-12, custom Sniffs), this may introduce redundancy or conflicts.

• Laravel-Specific Considerations:

  • Laravel’s PSR-4 autoloading and Blade template structure may require rule adjustments (e.g., ignoring resources/views in some cases).
  • Potential overlap with Laravel Pint (a PSR-12 auto-fixer), which could make this redundant unless custom rules are truly needed.

Integration Feasibility

• Core Compatibility:

  • PHP_CodeSniffer is a battle-tested tool with broad PHP ecosystem support.
  • Laravel projects already using PHP_CodeSniffer (e.g., for PHPMD, PHPCS) can integrate this with minimal effort.
  • Composer Dependency: Simple composer require shiftonelabs/codesniffer-standard installation.

• Customization:

  • Rules can be whitelisted/blacklisted via .phpcs.xml or .phpcs.xml.dist.
  • Example:

    <config name="standard" value="Shiftonelabs"/>
    <arg name="extensions" value="php,blade.php" /> <!-- If supporting Blade -->
    <file>./app</file>
    <exclude-pattern>*/tests/*</exclude-pattern>
    

• Tooling Synergy:

  • Works with:
    • Laravel Forge/Envoyer (run PHPCS in deploy hooks).
    • Git hooks (e.g., pre-commit via husky + phpcs).
    • CI/CD (e.g., fail builds on violations).

Technical Risk

Key Questions

1. Why PSR-2 + Custom Rules?

   • Is the team already using PSR-2, or is this a migration from a looser standard?
   • Are the custom rules critical (e.g., security, performance) or preference-based (e.g., indentation)?

2. Tooling Stack Conflicts

   • Does the team use Laravel Pint, PHPStan, or Psalm? Overlap could lead to redundant checks.
   • Example: Pint auto-fixes PSR-12; PHPCS may duplicate effort.

3. Enforcement Strategy

   • Will this be gated in CI (block merges) or informational (warnings only)?
   • How will violations be communicated (e.g., Slack alerts, PR comments)?

4. Blade Template Support

   • Should Blade files (*.blade.php) be analyzed? If so, how will custom directives (e.g., @php) be handled?

5. Long-Term Viability

   • Is the package actively maintained? (Low stars/activity may indicate risk.)
   • Are there plans to merge these rules into PHPCS core or another standard (e.g., PSR-22)?

Integration Approach

Stack Fit

• Laravel Ecosystem:

  • PHPCS Integration: Works seamlessly with Laravel’s existing tooling (e.g., phpcs CLI, Forge hooks).
  • CI/CD: Plugs into GitHub Actions, GitLab CI, or CircleCI via phpcs commands.
  • IDE Support: Integrates with PHPStorm (built-in PHPCS support) or VSCode (via extensions like "PHP Intelephense").

• Non-Laravel PHP:

  • Applicable to any PHP project using PSR-2 or PHP_CodeSniffer.
  • May require adjustments for non-PSR-4 autoloading (e.g., legacy app/ structures).

Migration Path

1. Assessment Phase:

   • Run PHPCS with the new standard on a staging branch:

     composer require shiftonelabs/codesniffer-standard --dev
     vendor/bin/phpcs --standard=Shiftonelabs app/
     

   • Document violations and prioritize fixes.

2. Pilot Enforcement:

   • Add to pre-commit hooks (e.g., via husky):

     {
       "hooks": {
         "pre-commit": "vendor/bin/phpcs --standard=Shiftonelabs --warning-severity=0 app/"
       }
     }
     

   • Configure CI to warn (not fail) initially.

3. Full Rollout:

   • Update .phpcs.xml to enforce the standard:

     <config name="standard" value="Shiftonelabs" />
     <config name="report" value="full" />
     <config name="reportFile" value="phpcs-report.xml" />
     

   • Fail CI builds on violations:

     # GitHub Actions example
     - name: Run PHPCS
       run: vendor/bin/phpcs --standard=Shiftonelabs --warning-severity=0 --error-severity=1 app/ || exit 1
     

4. Customization:

   • Override rules in .phpcs.xml:

     <rule ref="Shiftonelabs.SpecificRule" severity="warning" />
     <exclude-pattern>*/Tests/*</exclude-pattern>
     

Compatibility

• PHP Version: Compatible with PHP 7.4+ (PHPCS requirement).
• Laravel Version: No direct dependency, but assumes PSR-4 autoloading (Laravel 5.5+).
• Blade Support: Limited; may require custom Sniff classes for Blade-specific checks.
• Tooling Conflicts:
  • Laravel Pint: Disable Pint for files or use PHPCS for static analysis only.
  • PHPStan/Psalm: PHPCS focuses on style, not type safety.

Sequencing

1. Phase 1: Audit and fix critical violations (blockers).
2. Phase 2: Enforce in CI (warn-only).
3. Phase 3: Enforce in pre-commit hooks.
4. Phase 4: Gradually introduce stricter rules (e.g., custom Sniffs).

Operational Impact

Maintenance

• Rule Updates:

  • Monitor for PHPCS core updates that may obsolete custom rules.
  • Fork the package if upstream is abandoned (MIT license allows this).

• Configuration Drift:

  • Centralize .phpcs.xml in a monorepo or shared config to avoid divergence.
  • Document exceptions (e.g., // phpcs:ignore).

• Dependency Management:

  • Pin PHPCS version in composer.json to avoid breaking changes:

    "require-dev": {
      "squizlabs/php_codesniffer": "^3.7",
      "shiftonelabs/codesniffer-standard": "^1.0"
    }
    

Support

• Onboarding:
  • Provide a cheat sheet for common violations (e.g., "Why is this method indented differently?").
  • Example:

    [ERROR] Line 40: Missing file doc comment (Shiftonelabs.Files.FileComment.Missing)
    Fix: Add /** ... */ above the class.
    

• Debugging:
  • Teach teams to use --diff mode for targeted fixes:

    vendor/bin/phpcs --standard=Sh