Standards Laravel Package

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.
• Semantic, Not Just Cosmetic, Enforcement (v0.3.2): The addition of declare_strict_types to the fix rule set (issue #3) changes the package’s blast radius. standards:fix no longer only reformats whitespace and ordering — it now injects declare(strict_types=1); into every file it touches, which is a runtime behavior change. In Laravel terms this is the difference between a linting tool and a code-generation tool that alters type semantics.
• 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. This gap matters more now: strict types interact with Laravel’s string-typed request/input layer in ways Symfony-oriented defaults do not anticipate.
• 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).
• Risky-Rule Dependency: declare_strict_types is a risky fixer in PHP-CS-Fixer and only executes when the config sets setRiskyAllowed(true). Adoption teams must confirm whether the package’s shipped config enables risky rules globally — if it does, every other risky fixer becomes live at the same time, which is a much larger change surface than the release note implies.

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. With v0.3.2, --diff output will now show +declare(strict_types=1); hunks on every file — treat that as an expected signal, not a formatting regression.
• 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. However, standards:fix is now a mutating, semantics-changing command and should not be wired into auto-run hooks without a gate.

Technical Risk

• Strict-Types Runtime Breakage (new, highest severity): declare(strict_types=1); disables scalar type coercion for calls made from within the declaring file. Typical Laravel hazards:
  • function setLimit(int $n) called with $request->input('limit') (string) → TypeError.
  • Config/env values (env('X') returns string) passed to typed parameters.
  • Eloquent attribute values returned as strings passed into typed service methods.
  • JSON payloads, form data, and query strings never carry native ints — this is the single most common source of production incidents after strict-types adoption.
  • Mitigation: adopt per-directory (src/ new code first), never blanket-apply to app/Http, and require a full feature-suite run plus a staging smoke test on any commit that adds the declare.
• Diff Noise and Git History Churn: A single standards:fix run touches every PHP file (one-line insertion each), invalidating git blame, inflating PRs, and causing merge conflicts across long-lived branches. Mitigation: land it as one dedicated, isolated commit at a branch-quiet moment; add the hash to .git-blame-ignore-revs.
• 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 lack of stars/dependents raises concerns about long-term maintenance. Partially offset by v0.3.2: a community-authored fix merged within days of filing (#3) is a positive responsiveness signal. Mitigation strategies:
  • Fork the repository to customize Laravel-specific rules and pin the strict-types fixer out of the default set.
  • Monitor Rollerscapes’ updates and backport critical fixes if needed.

Key Questions

1. Strict-Types Rollout (new):
   • Does the shipped config set setRiskyAllowed(true), and if so which other risky fixers are now active that we have not evaluated?
   • Can declare_strict_types be disabled or scoped per path without forking (e.g., via Finder exclusions in our merged config)? We need it off for app/Http, config/, database/migrations/.
   • Who owns the decision to accept TypeError risk in existing controllers and jobs?
2. 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?
3. Adoption Strategy:
   • Should we replace existing Pint/PHPStan configs immediately, or phase in rules incrementally (e.g., start with PHP-CS-Fixer minus strict types, then PHPStan, then strict types)?
   • How will we handle legacy code that violates new standards? Will we use phpstan --generate-baseline or exclude specific paths?
4. 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?
5. 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?
   • Note: laravel/pint does not apply declare_strict_types by default, so running Pint alongside standards:fix may produce a fixer tug-of-war on the same file headers. Confirm rule-set precedence.
6. 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, further fix-rule additions in patch releases) in future Laravel versions? v0.3.2 demonstrates that a patch bump can change code semantics — pin exact 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:0.3.2
  

  Note: The --dev flag ensures the package is only installed in development, aligning with Laravel’s conventions. Given v0.3.2’s semantic change inside a patch release, pin the exact version rather than using a caret range, and let Renovate/Dependabot surface bumps for review.
• Toolchain Alignment:
  • PHP-CS-Fixer: Replaces or supplements Laravel Pint (PSR-12). Most rules are cosmetic and auto-fixable; the new declare_strict_types rule is not cosmetic and must be treated as a separate workstream.
  • 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

1. Assessment Phase (Week 1):
   • Run dry checks to baseline existing issues:

     composer require rollerscapes/standards:0.3.2 --dev
     vendor/bin/php-cs-fixer fix --dry-run --diff
     vendor/bin/phpstan analyse --level=5 --error-format=github
     

   • Separate the diff: filter the --diff output for declare(strict_types=1) hunks to quantify how many files would be touched. That number is your strict-types scope estimate.
   • Identify Laravel-specific false positives (e.g., Symfony rules triggering on Laravel code). Document these for customization.
2. Incremental Adoption (Weeks 2–6):
   • Phase 1 — Cosmetic lint only: Enforce PHP-CS-Fixer in pre-commit hooks with declare_strict_types excluded via a project-level override:

     // .php-cs-fixer.dist.php
     $config = require __DIR__.'/vendor/rollerscapes/standards/config.php';
     return $config->setRules(array_merge(
         $config->getRules(),
         ['declare_strict_types' => false],
     ));
     

     Example Husky config:

     {
       "hooks": {
         "pre-commit": "vendor/bin/php-cs-fixer fix --dry-run"
       }
     }
     

   • Phase 2 — Static analysis: Gradually increase PHPStan level (e.g., 5 → 7 → max) while fixing errors. Use phpstan --generate-baseline to temporarily ignore known issues.
   • Phase 3 — Strict types, path-scoped: Enable declare_strict_types for src//app/Services only, as one dedicated commit, with a full test-suite + staging verification. Extend directory coverage sprint over sprint.
   • Phase 4: 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>
     

3. 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())
         ->setRiskyAllowed(true)
         ->setRules(array_merge(
             Rollerscapes\Standards\Config::rules(),
             ['declare_strict_types' => false], // re-enable per path when ready
         ))
         ->setFinder($finder);
     

Compatibility

• No breaking API changes in v0.3.2 — it is a rule-set addition, not a signature change. Existing .neon/config consumers continue to load.
• Behavioral compatibility is the real question: PHP-CS-Fixer and Pint can both claim file headers; declare_strict_types is not part of Pint’s default preset, so mixed tooling will diverge. Standardize on one fixer for header-level rules.
• Framework compatibility: PHP 8.1+ / Laravel 10–11 unaffected. Strict types remain valid syntax back to PHP 7.0, so no parser risk — the risk is runtime, not parse-time.
• Third-party package code is out of scope (excluded via excludePaths), so the change only affects first-party files.

Sequencing

1. Pin 0.3.2 and run a dry-run diff audit (no writes).
2. Merge config with declare_strict_types => false; ship cosmetic linting into pre-commit and CI.
3. Raise PHPStan levels with a baseline.
4. Enable strict types in non-HTTP, non-config, non-migration directories; one isolated commit added to .git-blame-ignore-revs.
5. Expand directory by directory, gated on green test suite + staging smoke.
6. Only after full coverage: allow standards:fix to run unscoped.

Operational Impact

Maintenance

• Version pinning is now mandatory: v0.3.2 proves the project ships semantics-changing updates in patch releases. Adopt composer require "rollerscapes/standards:0.3.2" --dev (exact) and require a human review of every bump, with the diff filtered for fix-rule and risky-rule changes.
• Fork contingency: Given low stars/dependents, budget a half-day quarterly review of upstream releases; maintain a thin internal fork or config wrapper so a discontinuation does not block upgrades to Laravel 12+.
• Rule drift: Because the package owns the rule set, upgrades can silently introduce new fixers. Diff standards:check output before and after each bump in CI to make drift visible.

Support

• Developer support load will rise in Phase 3: strict-types TypeErrors surface at runtime, not at build time, so bugs land on developers and on-call rather than in CI. Pre-empt with a short internal note on the coercion rules and the $request->input() / env() string pitfall.
• Escalation path: no vendor SLA. Establish an internal owner (platform/DevEx engineer) as the single point of truth for the rule config; PRs touching .php-cs-fixer.dist.php or phpstan.neon require that owner’s review.
• Upstream engagement: the merged community fix for #3 suggests issues get attention; encourage filing upstream bugs rather than immediately forking.

Scaling

• CI cost: PHPStan level=max across a large Laravel monolith is the dominant cost; enable --parallel, cache the result cache between runs, and keep a baseline file to avoid re-reporting known errors. Budget a measurable CI minute increase and validate against the current pipeline duration.
• Repo-wide diffs: strict-types adoption scales linearly in diff size with codebase size — a 2,000-file repo produces a 2,000-file commit. Plan the rollout around team size, not just code volume, since every open branch will conflict.
• Monorepo/multi-app: apply per-application config so one app’s stricter posture does not block another’s release train.

Failure Modes

1. Production TypeError after an unscoped standards:fix — highest likelihood, highest severity. Guard: staging smoke test + scoped directory enablement.
2. Fixer tug-of-war between Pint and PHP-CS-Fixer producing non-deterministic CI failures. Guard: single canonical fixer; CI asserts fix --dry-run is clean.
3. Merge-conflict debt from the repo-wide strict-types commit. Guard: schedule during a branch-quiet window; publish the ignore-rev.
4. Silent no-op: if setRiskyAllowed(false) (or omitted), declare_strict_types never fires and teams wrongly believe they are compliant. Guard: add a fixture-file assertion in CI that a deliberately untyped file is flagged.
5. Configuration overwrite during merge with existing phpstan.neon, dropping project-specific ignoreErrors. Guard: config files under CODEOWNERS review.

Ramp-up

• Week 1: Pin, dry-run audit, quantify strict-types blast radius, publish findings. No writes to the repo.
• Week 2: Land merged config with strict types disabled; wire cosmetic lint into pre-commit and CI. Teams see value with near-zero risk.
• Weeks 3–4: PHPStan level ramp with baseline; one 60-minute enablement session on reading PHPStan output and using the baseline correctly.
• Weeks 5–6: Path-scoped strict types with an owner per directory; a shared runbook covering the declare, the exclusion list, and the rollback commit.
• Post-rollout: quarterly upstream review, rule-drift diff in CI, and a documented owner for the standards config.