Phpstan No Private Laravel Package

Technical Evaluation

Architecture Fit

The swissspidy/phpstan-no-private package aligns well with Laravel’s dependency injection (DI) principles and explicit encapsulation patterns. It enforces stricter visibility rules by treating @access private-annotated elements as deprecated, which complements Laravel’s:

• Service Container: Encourages constructor injection over private property access.
• Domain-Driven Design (DDD): Prevents accidental coupling by disallowing private method leaks.
• Testability: Public APIs are easier to mock and verify.

Key Synergies:

• Laravel’s protected vs. private: The package’s focus on @access private (not protected) avoids conflicts with Laravel’s common use of protected for internal class methods.
• PHPStan Integration: Leverages Laravel’s growing adoption of static analysis (e.g., laravel-pint, pestphp/pest) to enforce consistency.

Integration Feasibility

• Greenfield Projects: High feasibility—minimal refactoring needed if following Laravel’s DI patterns.
• Legacy Projects: Moderate to Low—existing private properties (e.g., in Eloquent models) may require mass refactoring to public getters/setters or dependency injection.
• Laravel-Specific Challenges:
  • Eloquent Models: Private properties (e.g., $fillable) are common but may violate the rule. Workarounds:
    • Use protected instead of private.
    • Annotate with @access public or @ignore in PHPStan config.
  • Service Providers: Private methods called from container bindings will trigger violations.

Technical Risk

Key Questions for the TPM

1. Codebase Maturity:

   • What percentage of classes use private properties/methods? (Target: <20% for smooth adoption.)
   • Are there critical paths (e.g., legacy APIs) that rely on private access?

2. Tooling Stack:

   • Is PHPStan already used in the team? If so, at what level (e.g., Level 5 vs. Level 10)?
   • Does the CI/CD pipeline support PHPStan 2.0+? (Check GitHub Actions/Pipelines.)

3. Team Readiness:

   • Has the team adopted Laravel’s DI patterns (e.g., constructor injection)?
   • Is there appetite for refactoring, or should this be a "new code only" rule?

4. Customization Needs:

   • Are there exceptions (e.g., internal libraries) that should bypass the rule?
   • Should the rule be configurable (e.g., @access private vs. @deprecated)?

5. Performance:

   • Will PHPStan runs be gated in PRs, or only in CI? (Affects developer velocity.)

Integration Approach

Stack Fit

Migration Path

1. Preparation Phase:

   • Audit: Run phpstan analyse --generate-baseline to identify violations.
   • Upgrade PHPStan:

     composer require --dev phpstan/phpstan:^2.0
     

   • Update Config:

     # phpstan.neon
     includes:
         - vendor/swissspidy/phpstan-no-private/extension.neon
     parameters:
         level: 8  # Start with Level 8 (strict) to avoid false positives
     

2. Pilot Phase:

   • New Features: Enforce the rule only in new code (use pathExclusionFilters).
   • Critical Paths: Refactor high-impact modules (e.g., API controllers) first.

3. Full Adoption:

   • CI/CD Integration:

     # .github/workflows/phpstan.yml
     - name: PHPStan
       run: vendor/bin/phpstan analyse --level=max --error-format=github
     

   • Developer Workflow:
     • Add PHPStan to composer.json scripts:

       "scripts": {
           "test": [
               "phpstan"
           ]
       }
       

     • Use phpstan --generate-baseline to suppress known issues temporarily.

Compatibility

• Laravel 8+: High compatibility with DI patterns; minimal refactoring needed.
• Laravel 7.x: Moderate—may require updating to use protected instead of private.
• Legacy Code:
  • Workarounds:
    • Replace private with protected (less strict but avoids violations).
    • Use public getters/setters for private properties.
    • Annotate exceptions:

      /** @ignore */
      private function legacyMethod() { ... }
      

Sequencing

1. Phase 1: Configuration (1–2 days)

   • Upgrade PHPStan and install the package.
   • Configure phpstan.neon to exclude non-critical paths.

2. Phase 2: Pilot (2–4 weeks)

   • Enforce rules in a single module (e.g., API routes).
   • Refactor violations iteratively.

3. Phase 3: Full Rollout (4–8 weeks)

   • Expand to all new code.
   • Gradually migrate legacy code (prioritize high-value areas).

4. Phase 4: Enforcement (Ongoing)

   • Treat violations as CI/CD blockers.
   • Deprecate @access private annotations in favor of protected or public APIs.

Operational Impact

Maintenance

• Pros:
  • Reduced Technical Debt: Encourages explicit APIs, improving maintainability.
  • Consistent Patterns: Aligns with Laravel’s DI and SOLID principles.
• Cons:
  • Refactoring Burden: Legacy private properties may require mass updates.
  • Configuration Drift: PHPStan rules may need tuning over time (e.g., new exceptions).

Support

• Developer Onboarding:
  • Training Needed: Explain why private properties are discouraged (e.g., testability, coupling).
  • Documentation: Add a CONTRIBUTING.md section on PHPStan rules.
• Common Issues:
  • False Positives: Eloquent models or third-party packages may trigger violations.
  • Tooling Confusion: Developers may not understand @access private vs. @ignore.

Scaling

• Performance:
  • PHPStan Overhead: Adds ~5–15% to CI/CD time (mitigate with caching).
  • Local Dev: Use phpstan --memory-limit=1G to avoid timeouts.
• Team Size:
  • Small Teams: Easier to coordinate refactoring.
  • Large Teams: Use feature flags or module-by-module adoption.
• Monorepos:
  • Configure PHPStan per-package (e.g., exclude vendor/ and node_modules/).

Failure Modes

Ramp-Up

1. Training:

   • Workshop: 1-hour session on PHPStan Level 10 and the package’s goals.
   • Cheat Sheet: Document common fixes (e.g., private → protected, getters/setters).

2. Pilot Project:

   • Select a low-risk module (e.g., a new feature