Phpstan No Safe Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling Alignment: The package remains a PHPStan extension, reinforcing its role in defensive programming and security-first architectures. The 1.0.0 release solidifies its position as a mature static analysis tool for blocking unsafe operations (e.g., thecodingmachine/safe). This aligns with projects prioritizing type safety, runtime security, and compliance (e.g., fintech, healthcare, CLI tools).
• Complementarity with Existing Tools: Continues seamless integration with:
  • PHPStan (static analysis).
  • PSR-12/PSR-2 (coding standards).
  • Laravel’s dependency injection (where safe might be used for dynamic operations).
• Security-First Mindset: Targets projects where runtime exceptions (e.g., file operations, shell commands) are critical failure points. Ideal for:
  • Financial systems (e.g., payment processing).
  • Healthcare/Compliance-heavy apps (e.g., HIPAA/GDPR).
  • CLI tools with user-provided input.

Integration Feasibility

• Low-Coupling Design: As a PHPStan extension, it does not modify runtime behavior but enforces rules at analysis time. No changes to production codebase required beyond PHPStan configuration.
• Laravel-Specific Considerations:
  • Artisan Commands: High risk of safe usage (e.g., Artisan::call(), shell commands). The package will flag these unless explicitly whitelisted.
  • Service Providers: Dynamic method calls (e.g., app()->make() with unsafe parameters) may trigger violations.
  • Third-Party Packages: Many PHP libraries use safe under the hood (e.g., spatie/laravel-medialibrary). Requires vendor-level analysis or selective whitelisting.
• Toolchain Compatibility:
  • Works with PHP 8.0+ (PHPStan’s minimum version).
  • Compatible with Laravel 9+ (PHP 8.0+).
  • CI/CD Integration: Can be added to existing PHPStan pipelines (e.g., GitHub Actions, GitLab CI) without disrupting workflows.

Technical Risk

Key Questions

1. Security Policy Alignment:

   • Does the organization’s security policy explicitly prohibit safe usage, or is this a proactive measure?
   • Are there approved alternatives (e.g., custom wrappers, Laravel’s Filesystem abstractions)?

2. Impact Assessment:

   • What percentage of the codebase uses safe or similar patterns (e.g., eval(), shell_exec())?
   • Which third-party packages rely on safe? Can they be replaced or patched?

3. Tooling Maturity:

   • Has PHPStan been fully adopted in the team’s workflow? If not, this may introduce resistance.
   • Are there existing static analysis tools (e.g., Psalm, Pest) that could conflict?

4. False Positive Handling:

   • What process exists for whitelisting exceptions (e.g., vendor code, legacy systems)?
   • Will the team need to maintain a custom rule set for this package?

5. Long-Term Maintenance:

   • Who will update the PHPStan extension if the package evolves (e.g., new rules)?
   • How will this integrate with dependency updates (e.g., if safe is deprecated upstream)?

Integration Approach

Stack Fit

• Primary Use Case: Laravel + PHPStan environments where:
  • Static analysis is already part of the CI/CD pipeline (e.g., phpstan/phpstan in composer.json).
  • Security is a top priority (e.g., fintech, SaaS platforms).
• Secondary Use Case: Monolithic PHP apps (non-Laravel) using PHPStan for quality gates.
• Unsuitable for:
  • Projects not using PHPStan (requires adoption effort).
  • Microservices where safe is heavily used in inter-service communication (may require architectural refactoring).

Migration Path

1. Assessment Phase (1-2 weeks):

   • Run PHPStan with the extension in a staging environment to identify violations.
   • Audit third-party dependencies for safe usage (tools: composer why, roave/security-advisories).
   • Document false positives and whitelist rules in phpstan.neon.

2. Pilot Phase (2-4 weeks):

   • Integrate into a single module/service (e.g., a non-critical feature).
   • Train developers on how to refactor (e.g., replace safe with Laravel’s Storage facade).
   • Validate CI/CD pipeline changes (e.g., GitHub Actions workflow updates).

3. Rollout Phase (4-8 weeks):

   • Gradually enable for all modules, starting with high-risk areas (e.g., file uploads, CLI commands).
   • Deprecate safe usage in internal libraries (replace with custom wrappers).
   • Update documentation to reflect new security constraints.

Compatibility

• Laravel-Specific:
  • Artisan Commands: Replace safe with Laravel’s Process facade or Symfony/Process.
  • Service Container: Use app()->bound() checks instead of dynamic safe calls.
  • Blade Templates: Avoid {{ }} with user input; use {{{ }}} with sanitization.
• PHPStan Configuration:

  includes:
      - vendor/wyrihaximus/phpstan-no-safe/extension.neon
  level: max
  whitelistPaths:
      - src/Exceptions/WhitelistedSafeUsage.php  # Custom exceptions for approved uses
  

• Dependency Conflicts:
  • If a package (e.g., spatie/laravel-medialibrary) uses safe, consider:
    • Forking the package to remove safe dependency.
    • Submitting a PR upstream.
    • Whitelisting the specific usage (if justified).

Sequencing

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: Over time, phpstan.neon may accumulate custom whitelists, making it hard to maintain.
  • Mitigation: Regularly audit whitelists (e.g., quarterly) and remove unused entries.
• Dependency Updates:
  • If thecodingmachine/safe or PHPStan releases breaking changes, the extension may need updates.
  • Mitigation: Pin versions in composer.json until stability is confirmed.
• Team Knowledge:
  • Developers must understand why safe is blocked and how to refactor.
  • Mitigation: Run workshops and document common patterns (e.g., "Use Storage::disk()->put() instead of safe").

Support

• Developer Experience:
  • Pros: Catches security issues early (during development), reducing runtime crashes.
  • Cons: May slow down PR reviews if many violations exist initially.
• Security Team Burden:
  • Increased false positive triage if whitelisting isn’t carefully managed.
  • Mitigation: **