Php Conventions Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Enforces PSR-12 and PHPStan conventions, aligning with modern Laravel best practices (Laravel already adheres to PSR standards).
  • Reduces cognitive load by standardizing code structure, improving readability and maintainability.
  • Complements Laravel’s existing tooling (e.g., laravel-shift/blueprint, phpstan/extension-installer).
  • Lightweight (~7 stars suggests niche but targeted utility; likely low overhead).

• Cons:

  • Overlap with existing tools: Laravel’s ecosystem already includes:
    • phpstan/extension-installer (for PHPStan integration).
    • dealerdirect/phpcodesniffer-composer-installer (for PHPCS).
    • laravel/pint (for auto-formatting).
  • Limited Laravel-specific features: Focuses on generic PHP conventions, not Laravel’s unique patterns (e.g., Facades, Service Providers, Blade templates).
  • No built-in CI/CD or testing hooks: Requires manual integration with Git hooks, CI pipelines, or IDE plugins.

• Key Fit Areas:

  • Greenfield projects adopting strict conventions from day one.
  • Legacy Laravel apps needing a convention audit without heavy refactoring.
  • Teams lacking standardized coding guidelines or relying on manual reviews.

Integration Feasibility

• Low-to-Medium Effort:

  • Installation: Composer-based (composer require drupol/php-conventions), minimal setup.
  • Configuration: Requires phpstan.neon and PHPCS rules alignment (may conflict with existing configs).
  • Toolchain Compatibility:
    • Works with PHPStan, PHPCS, and PHPUnit (via PHPCS’s phpunit ruleset).
    • No native Laravel Service Provider: Must be invoked via CLI or CI (e.g., GitHub Actions, GitLab CI).
  • IDE Support: Can integrate with PHPStorm or VSCode via PHPCS plugins.

• Potential Conflicts:

  • Custom PHPCS/PHPStan rules: May need to override or merge with existing rulesets.
  • Performance: PHPStan can be slow; running it in CI may increase build times.
  • Developer Experience: Enforcing conventions strictly could slow down initial development if not properly scoped.

Technical Risk

Key Questions for TPM

1. Why not leverage Laravel’s built-in tools (e.g., pint, phpstan/extension-installer) instead?
   • Does this package offer unique value (e.g., pre-configured rules, better IDE integration)?
2. How will this integrate with existing CI/CD?
   • Will it replace or augment current linting steps (e.g., PHPCS, PSalm)?
3. What’s the adoption scope?
   • Will it apply to all code or only new features/legacy refactors?
4. How will rule violations be handled?
   • Will it block merges (Git hooks) or require manual fixes (CI failures)?
5. Performance Impact:
   • Has PHPStan execution time been profiled for the codebase size?
6. Team Buy-in:
   • Are developers familiar with PSR-12/PHPStan, or will this require training?

Integration Approach

Stack Fit

• Best For:

  • Laravel 8+ (PSR-12 compliant by default).
  • Teams using PHPStan or PHPCS (or willing to adopt them).
  • Projects with monorepo or multi-package structures (enforces consistency).

• Poor Fit:

  • Projects heavily customized with non-PSR-12 legacy code.
  • Teams without CI/CD pipelines or CLI access.
  • Apps using alternative static analyzers (e.g., PSalm, Rector).

• Complementary Tools:

  Tool	Purpose
  phpstan/extension-installer	Auto-load PHPStan extensions.
  dealerdirect/phpcodesniffer-composer-installer	Auto-install PHPCS.
  laravel/pint	Auto-format code (reduces PHPCS noise).
  rector/rector	Automate refactoring (if conventions are violated).

Migration Path

1. Assessment Phase:
   • Run phpcs and phpstan against the codebase to identify current violations.
   • Document existing rulesets (PHPCS/PHPStan) to avoid conflicts.
2. Pilot Integration:
   • Install drupol/php-conventions in a feature branch or new module.
   • Configure phpstan.neon and PHPCS rulesets to match Laravel’s defaults.
   • Test with a subset of developers to gather feedback.
3. CI/CD Integration:
   • Add to CI pipeline (e.g., GitHub Actions):

     - name: PHPStan
       run: vendor/bin/phpstan analyse --level=max
     - name: PHPCS
       run: vendor/bin/phpcs --standard=phpconventions
     

   • Set failure thresholds (e.g., block PRs on critical violations).
4. Developer Onboarding:
   • Add pre-commit hooks (e.g., husky + phpcs).
   • Document common fixes (e.g., "Use === instead of ==").
5. Gradual Rollout:
   • Start with new code only, then expand to legacy modules.
   • Use Rector to automate fixes where possible.

Compatibility

• Laravel-Specific Considerations:
  • Blade Templates: Not covered by PHPStan/PHPCS; may need custom rules.
  • Facades/Helpers: Some Laravel patterns (e.g., Helper::str()) may violate PSR-12.
  • Database Migrations: Often exempt from strict linting (configure exclusions).
• Exclusion Strategy:
  • Use phpstan.neon exclusions:

    excludes:
      - migrations/*
      - storage/*
      - vendor/*
    

  • PHPCS ignore patterns:

    <arg value="--ignore=app/Helpers.php"/>
    

Sequencing

Operational Impact

Maintenance

• Pros:
  • Low maintenance: MIT license, minimal dependencies.
  • Community support: PHPStan/PHPCS ecosystems are mature.
• Cons:
  • Rule Updates: PHPStan/PHPCS may introduce breaking changes (e.g., stricter PSR-12 rules).
  • Custom Rules: Any Laravel-specific extensions require manual upkeep.
• Mitigation:
  • Pin versions of phpstan/phpstan and squizlabs/php_codesniffer in composer.json.
  • Monitor upstream issues (e.g., PHPStan GitHub).

Support

• Developer Support:
  • Initial Ramp-Up: Expect 1-2 weeks for teams unfamiliar with PHPStan/PHPCS.
  • Common Issues:
    • False positives (e.g., Laravel’s collect() method triggering unused-function rules).
    • IDE misconfigurations (e.g., PHPCS not running in VSCode).
  • Solution: Maintain a troubleshooting doc with Laravel-specific examples.
• TPM Support:
  • Escalation Path: For complex rule conflicts, engage with PHPStan/PHPCS communities.
  • Tooling: Use phpstan --generate-baseline to suppress known issues temporarily.

Scaling

• Performance:
  • PHPStan: Scales poorly with large codebases (>1M LOC). Mitigate