Technical Evaluation

Architecture Fit

Code Quality Standardization: The package provides a pre-configured, opinionated set of PHP standards (PHP-CS-Fixer, PHPStan, PHPUnit) that aligns with Laravel’s emphasis on maintainability and consistency. It enforces PSR-12, PHPStan static analysis, and PHPUnit best practices, which are critical for long-term Laravel project health.
Laravel Compatibility: While the package is PHP 8.1+ compatible (aligning with Laravel 10/11), its lack of explicit Laravel-specific rules (e.g., Blade templates, Eloquent, Facades) is a critical gap. The inclusion of phpstan/phpstan-symfony suggests partial awareness of Laravel’s ecosystem, but no documentation confirms coverage of Laravel’s core components.
Modularity and Extensibility: The package’s reliance on composer dependencies and configuration files (.php-cs-fixer.dist.php, phpstan.neon) allows for incremental adoption and customization. Existing Laravel projects using these tools individually would face minimal disruption, but conflicts may arise if overlapping configurations exist (e.g., custom PHPStan rules vs. Rollerscapes’ defaults).
Toolchain Synergy: The package unifies Laravel’s existing tooling (Pint for PSR-12, PHPStan for static analysis) under a single dependency, reducing maintenance overhead and configuration drift. However, Laravel’s built-in phpunit.xml and phpstan.neon may require manual merging to avoid conflicts.

Integration Feasibility

Low-Coupling Design: The package is configuration-driven, making it easy to override or extend existing tooling. Laravel’s phpunit.xml and phpstan.neon can be merged without conflicts, but explicit guidance is lacking.

CI/CD Readiness: The package’s focus on static analysis and linting makes it ideal for pre-commit hooks and CI pipelines. Example GitHub Actions workflow:

jobs:
  standards:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer require rollerscapes/standards --dev
      - run: vendor/bin/php-cs-fixer fix --dry-run --diff
      - run: vendor/bin/phpstan analyse --level=max --error-format=github

Key: The --diff flag for PHP-CS-Fixer and --error-format=github for PHPStan improve debuggability in CI.

Artisan Integration: The package’s Artisan commands (standards:check, standards:fix, standards:analyze) provide a Laravel-native way to run checks, reducing friction for developers already familiar with Laravel’s CLI.

Technical Risk

Undocumented Laravel-Specific Rules: The lack of Blade template, Eloquent, or Facade-specific rules is a major risk. Without explicit guidance, the TPM must:
- Audit whether phpstan-symfony covers Laravel’s core components (e.g., Illuminate\Contracts, Illuminate\Support\Facades).
- Customize PHPStan to avoid false positives (e.g., using ignoreErrors or excludePaths).
PHPStan Strictness: Upgrading to PHPStan 2.0 (v0.3.0) may introduce false positives in legacy Laravel codebases. The TPM should:
- Baseline existing errors before enforcing strict rules.
- Use phpstan --generate-baseline to temporarily ignore known issues while fixing others.
Dependency Bloat: The package pulls in PHPStan extensions (Doctrine, Symfony, PHPUnit) that may not all be needed. A TPM should:
- Prune unused dependencies to avoid performance overhead.
- Verify that phpstan/phpstan-doctrine and phpstan/phpstan-symfony are necessary for the project.
Future-Proofing: The package’s last release in 2026 and lack of stars/dependents raise concerns about long-term maintenance. Mitigation strategies:
- Fork the repository to customize Laravel-specific rules.
- Monitor Rollerscapes’ updates and backport critical fixes if needed.

Key Questions

Laravel-Specific Coverage:
- Does the package include rules for Blade templates, Eloquent relationships, or Laravel-specific annotations (e.g., @mixin, @inject)? If not, how will we customize PHPStan to avoid false positives?
- Are there known conflicts with Laravel’s laravel/phpstan package? Should we merge configurations or replace one with the other?
Adoption Strategy:
- Should we replace existing Pint/PHPStan configs immediately, or phase in rules incrementally (e.g., start with PHP-CS-Fixer, then PHPStan)?
- How will we handle legacy code that violates new standards? Will we use phpstan --generate-baseline or exclude specific paths?
Performance Impact:
- What is the runtime overhead of PHPStan’s level=max in a large Laravel monolith? Can we cache results (e.g., via phpstan --generate-baseline) to reduce CI/CD noise?
- Does the package support parallel analysis (e.g., PHPStan’s --parallel) for faster execution?
Tooling Conflicts:
- How will this package interact with Laravel’s built-in phpunit.xml or phpstan.neon? Are there known conflicts with laravel/pint or laravel/phpstan?
- Can we disable specific rules (e.g., Symfony-related) without forking the package?
Maintenance Plan:
- Who will update the package if Rollerscapes stops maintaining it? Should we fork and customize it for Laravel-specific needs?
- How will we handle breaking changes (e.g., PHPStan 2.0 upgrades) in future Laravel versions?

Integration Approach

Stack Fit

PHP 8.1+ and Laravel 10/11: The package is fully compatible with Laravel’s current and near-future PHP versions. No version conflicts expected.
Composer Ecosystem: Integrates seamlessly with Laravel’s dependency management. Install via:
```
composer require --dev rollerscapes/standards
```
Note: The --dev flag ensures the package is only installed in development, aligning with Laravel’s conventions.
Toolchain Alignment:
- PHP-CS-Fixer: Replaces or supplements Laravel Pint (PSR-12). The package’s rules are auto-fixable, reducing manual effort.
- PHPStan: Extends laravel/phpstan with additional rules (Doctrine, Symfony). Critical: Verify if this duplicates or conflicts with existing Laravel PHPStan configs.
- PHPUnit: Enforces internal test marking (useful for Laravel’s test suites). Risk: May conflict with Laravel’s phpunit.xml if not merged carefully.

Migration Path

Assessment Phase (Week 1):
- Run dry checks to baseline existing issues:
```
composer require rollerscapes/standards --dev
vendor/bin/php-cs-fixer fix --dry-run --diff
vendor/bin/phpstan analyse --level=5 --error-format=github
```
- Identify Laravel-specific false positives (e.g., Symfony rules triggering on Laravel code). Document these for customization.
Incremental Adoption (Weeks 2–4):
- Phase 1: Enforce PHP-CS-Fixer in pre-commit hooks (via Laravel Pint or Husky). Example Husky config:
```
{
  "hooks": {
    "pre-commit": "vendor/bin/php-cs-fixer fix --dry-run"
  }
}
```
- Phase 2: Gradually increase PHPStan level (e.g., 5 → 7 → max) while fixing errors. Use phpstan --generate-baseline to temporarily ignore known issues.
- Phase 3: Update PHPUnit tests to mark internal tests (if using phpunit.xml overrides). Merge with Laravel’s default config:
```
<phpunit>
  <extensions>
    <extension class="Rollerscapes\Standards\PHPUnit\InternalTestExtension"/>
  </extensions>
</phpunit>
```
Configuration Merge (Ongoing):
- PHP-CS-Fixer: Merge with existing .php-cs-fixer.dist.php. Prioritize project-specific rules over Rollerscapes’ defaults:
```
return (new PhpCsFixer\Config())
    ->setRules(Rollerscapes\Standards\Config::
```

Standards Laravel Package