Onr Phpcs Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package enforces PSR-12 (PHP-FIG) and Laravel-specific coding standards via PHP_CodeSniffer (PHPCS). It integrates seamlessly into Laravel’s ecosystem, aligning with:
  • Laravel’s built-in PHPCS rules (e.g., laravel standard).
  • CI/CD pipelines (e.g., GitHub Actions, GitLab CI) for automated linting.
  • Developer workflows (e.g., pre-commit hooks via php-cs-fixer or robo.phar).
• Extensibility: Supports custom rules via PHPCS’s Sniff classes, allowing TPMs to enforce team-specific standards (e.g., docblock formats, naming conventions).
• Tooling Synergy: Complements existing Laravel tools like:
  • Laravel Pint (auto-fixer).
  • PHPStan/Psalm (static analysis).
  • Laravel Valet/Sail (local dev environments).

Integration Feasibility

• Low Friction: No database/migrations or complex dependencies—pure composer-based PHPCS integration.
  • Install via:

    composer require --dev onramplab/onr-phpcs-laravel
    

  • Configure in phpcs.xml or phpcs.xml.dist (Laravel’s default PHPCS config location).
• PHPCS Ecosystem: Leverages existing PHPCS plugins (e.g., squizlabs/php_codesniffer, dealerdirect/phpcodesniffer-composer-normalize).
• IDE Support: Works with PHPStorm, VSCode (via extensions like "PHP CS Fixer"), and Laravel IDE Helper.

Technical Risk

Key Questions for TPM

1. Standardization Needs:
   • Does the team require beyond PSR-12/Laravel standards (e.g., custom docblock templates)?
   • Should this replace or complement existing tools (e.g., pint, phpstan)?
2. CI/CD Integration:
   • How will violations block merges (e.g., GitHub branch protection rules)?
   • Should it run in parallel with other checks (e.g., tests, security scans)?
3. Developer Adoption:
   • Will local linting be enforced (e.g., via pre-commit hooks)?
   • How will false positives be handled (e.g., rule exceptions in phpcs.xml)?
4. Long-Term Maintenance:
   • Who owns rule updates (e.g., if Laravel’s standards evolve)?
   • Should this be vendor-locked or forked for customization?

Integration Approach

Stack Fit

• Laravel Native: Designed for Laravel’s PSR-12 + framework-specific standards (e.g., blade template rules).
• PHPCS Ecosystem: Works with:
  • PHP_CodeSniffer (core dependency).
  • PHP CS Fixer (auto-fix violations).
  • Parallel Linting (via php-parallel-lint for large codebases).
• Toolchain Compatibility:
  • CI/CD: GitHub Actions, GitLab CI, CircleCI (standard PHPCS step).
  • Local Dev: VSCode/PHPStorm plugins, robo.phar tasks.
  • Docker: Include in Dockerfile for consistent linting across environments.

Migration Path

1. Assessment Phase:
   • Audit current phpcs.xml for conflicts.
   • Run a dry pass to identify violations:

     vendor/bin/phpcs --standard=onramplab/onr-phpcs-laravel app/
     

2. Incremental Rollout:
   • Phase 1: Add to composer.json dev dependencies.
   • Phase 2: Update phpcs.xml to include the new standard.
   • Phase 3: Integrate into CI/CD (fail builds on violations).
3. Developer Onboarding:
   • Document allowed exceptions (e.g., legacy code).
   • Provide a fix-it guide (e.g., using pint for auto-formatting).

Compatibility

• Laravel Versions: Works with Laravel 8+ (PSR-12 is framework-agnostic).
• PHP Versions: Requires PHP 8.0+ (aligns with Laravel’s support).
• PHPCS Version: Pin to a stable PHPCS release (e.g., ^3.7) in composer.json.
• Custom Rules: Extend via:

  <!-- phpcs.xml -->
  <config name="installed_paths" value="vendor/onramplab/onr-phpcs-laravel"/>
  <rule ref="onramplab/onr-phpcs-laravel"/>
  

Sequencing

1. Pre-Requirements:
   • Ensure PHPCS is installed globally or via Composer.
   • Resolve any existing PHPCS conflicts (e.g., custom rules overriding Laravel’s).
2. Core Integration:
   • Add to composer.json:

     "require-dev": {
         "onramplab/onr-phpcs-laravel": "^1.0"
     }
     

   • Configure phpcs.xml:

     <config name="standard" value="onramplab/onr-phpcs-laravel"/>
     

3. CI/CD Pipeline:
   • Add a step (example for GitHub Actions):

     - name: Run PHPCS
       run: vendor/bin/phpcs --standard=onramplab/onr-phpcs-laravel --error-severity=5
     

4. Local Workflow:
   • Set up pre-commit hooks (e.g., via husky + php-cs-fixer).
   • Configure IDEs to auto-fix where possible.

Operational Impact

Maintenance

• Low Effort:
  • Updates via composer update.
  • Rule adjustments via phpcs.xml (no code changes).
• Dependency Management:
  • Pin PHPCS version to avoid breaking changes.
  • Monitor for upstream Laravel standard updates.
• Customization:
  • Fork the package if heavy customization is needed (Unlicense permits this).

Support

• Troubleshooting:
  • Common issues: false positives, PHPCS configuration errors.
  • Debug with:

    vendor/bin/phpcs --config-show
    vendor/bin/phpcs --verbose app/
    

• Documentation:
  • Internal wiki for:
    • How to add exceptions (e.g., @ignore annotations).
    • CI/CD troubleshooting (e.g., caching results).
  • Link to PHPCS docs for advanced use cases.
• Community:
  • Limited (0 stars), but PHPCS community is mature for support.

Scaling

• Performance:
  • Large Codebases: Use --parallel or cache results:

    vendor/bin/phpcs --cache=/tmp/phpcs-cache
    

  • Distributed Teams: Centralize phpcs.xml in a monorepo or shared config repo.
• Rule Scaling:
  • Modular Rules: Split into multiple phpcs.xml files (e.g., phpcs-app.xml, phpcs-tests.xml).
  • Dynamic Standards: Use PHPCS’s <arg> to toggle rules:

    <arg name="extensions" value="php,blade" />
    

Failure Modes