Framework Laravel Package

Technical Evaluation

Architecture Fit

• Baseline moves from v2.0.0 → v2.1.7 (patch-level, no architectural shift):
  • The v2.1.7 release notes contain only a diff link (v2.1.6...v2.1.7). By SemVer and by the absence of any contradicting signal, this is a patch release with no breaking changes — no new framework baseline, no new PHP floor, no new required dependencies.
  • The Laravel 12 / PHP 8.2+ baseline established in v2.0.0 stands unchanged. Nothing in this release reopens the architecture question.
• The meaningful signal is line maturity, not the patch itself:
  • The package has moved from the assessment's v2.0.0 cutover point to v2.1.7 — a minor line plus seven patch releases. That cadence indicates the 2.x branch is actively maintained and has absorbed early-adopter defects, which materially lowers the "we'd be adopting a fresh major" risk profile recorded in the prior assessment.
  • Operational read: the prior assessment's framing of v2.0.0 as a decision to adopt an unproven major should be retired. v2.1.7 is the current target, and v2.0.0 is now a historical waypoint rather than the recommended landing spot.
• Hybrid architecture trade-offs unchanged:
  • Laravel↔WordPress bridge value proposition (Eloquent over wp_*, typed bindings for WP_User|null / WPDB, container-dispatched hooks) is untouched.
  • Ecosystem gating remains the dominant architectural constraint — any companion package still not Laravel 12/Symfony 7-ready blocks the upgrade regardless of how many patches the framework package ships.
  • Performance profile unchanged: WordPress bootstrap still dominates hybrid request time; Laravel 12's leaner skeleton is a small constant, not a step change.

Integration Feasibility

• Core Laravel Compatibility:
  • Pros:
    • Target constraint should now be ^2.1.7, not ^2.0 — you get six patch releases of hardening for free on a single Composer constraint.
    • Patch-only delta from the v2.0.0 assessment baseline means no re-litigation of the Laravel 12 pre-requisite; the sequenced plan (host app → Laravel 12 → package cutover) is still correct.
    • Active patch cadence is a positive maintenance signal for a package sitting at the seam of two ecosystems.
  • Cons:
    • No UPGRADE guide or changelog beyond a compare URL. The prior assessment flagged "sparse release notes" at v2.0.0; that gap has now persisted across the entire 2.x line rather than being a one-off. This is a standing process deficiency, not a transient one.
    • Cumulative delta is now undocumented: we have no vetted view of what shipped in 2.1.0–2.1.6 (minor releases may add config keys, bindings, or deprecations). Anyone upgrading directly from 1.10.x → 2.1.7 must diff seven releases, not one.
    • Consumers still on Laravel 10/11 remain blocked — the major-version gate is unchanged by this release.
• WordPress Integration:
  • Pros: No change to typed bindings or strict-mode friendliness; the v1.10.0 nullable-type work remains inherited.
  • Cons: Blast radius unchanged — a Laravel major upgrade plus WordPress plugin compatibility testing still share one release window. Patch releases do not reduce that.

Technical Risk

Key Questions

1. Upgrade Sequencing: Is the host application on Laravel 12 yet? If not, that workstream still gates everything — v2.1.7 does not soften this.
2. Cumulative Change Inventory: Who owns producing an internal changelog for v2.0.0 → v2.1.7? Upstream provides only a compare link. This is now a standing deliverable, not a one-time task.
3. 2.1.x Adoption Scope: Did 2.1.0 introduce new config keys, service-provider bindings, or deprecations we should adopt (or explicitly opt out of) during the cutover, rather than landing on 2.0 semantics?
4. Current State of Our Environments: Are any environments already on a 2.0.x patch? If so, v2.1.7 is a routine bump and the upgrade plan should be re-baselined accordingly; if all are on 1.10.x, the full plan stands.
5. Ecosystem Readiness: Which companion packages remain Laravel 12-incompatible, and are any load-bearing for the hybrid layer?
6. Support Policy for v1.x: How long does 1.10.x receive security/type fixes? Active 2.1.x patching is encouraging, but we still need a dated v1 sunset to decouple the two workstreams.
7. PHP Version Strategy: Confirm the standard (8.3 for headroom vs. 8.4 forward-looking); confirm 8.2 remains in the CI matrix as the Laravel 12 floor.
8. Rollback: Can we revert the package patch independently of the host framework upgrade? (It must be a separate commit.)

Integration Approach

Stack Fit

• Target constraint updates to ^2.1.7 — this supersedes the ^2.0 recommendation in the prior assessment. No other stack-fit changes.
• Keep the Laravel 12 conventions and strict-mode scoping exactly as planned: APP_STRICT_MODE=true in non-production first, expanded only after the hybrid layer is clean under PHPStan level 8.
• PHP matrix remains 8.2 / 8.3 / 8.4, with 8.3 primary.
• WordPress: unchanged — WP_* access behind typed container bindings; plugin/theme code treated as untrusted input at the adapter boundary.
• Database: unchanged — Laravel schema management for new tables; wp_* read-mostly via Eloquent with explicit casts.

Migration Path

1. Phase 0: Laravel 12 Host Upgrade (Prerequisite — unchanged)

   • Upgrade the app to Laravel 12 while staying on wpstarter/framework ^1.10.
   • Pre-flight the wider dependency graph against the new target:

     composer why-not laravel/framework ^12.0
     composer why-not wpstarter/framework ^2.1
     

   • CI green on 8.2/8.3/8.4 before touching the package version.

2. Phase 1: Package Cutover on a Branch (target updated)

   • Land directly on the current patch rather than 2.0.0 — there is no reason to adopt a superseded release:

     composer require wpstarter/framework:^2.1.7 --with-all-dependencies
     

   • Diff v1.10.x...v2.1.7, and separately inventory v2.0.0...v2.1.7 so newly added config keys and bindings are deliberately adopted or ignored.
   • Run phpstan analyse --level 8 app/WpStarter plus the full PHPUnit suite.

3. Phase 2: Hybrid Behavior Validation (unchanged)

   • Exercise hook dispatch, REST endpoints, and admin screens on staging WordPress.
   • Explicitly test nullable/optional WordPress data paths and Laravel 12 cache/session/queue defaults.

4. Phase 3: Production Rollout

   • Canary/soak; keep ^1.10 revertible on the previous release branch.
   • If already on 2.0.x: treat v2.1.7 as a standalone, low-ceremony patch deploy with standard regression coverage — do not bundle it with unrelated framework work.

Compatibility

• Constraints:

  "require": {
      "php": "^8.2",
      "laravel/framework": "^12.0",
      "wpstarter/framework": "^2.1.7"
  }
  

• Breaking surface to verify: unchanged from the v2.0.0 assessment (service-provider registration, published config keys, public method signatures, Symfony 7 tightening) — plus anything introduced in 2.1.0–2.1.6, which upstream does not document.
• WordPress Versions: WordPress 6.5+, validated across the PHP matrix.

Sequencing

1. Step 1 — Lock production branches to wpstarter/framework ^1.10.
2. Step 2 — Upgrade host app to Laravel 12; CI green on full matrix.
3. Step 3 — Build the internal v2.0.0...v2.1.7 changelog; branch-cut to ^2.1.7; complete API diff and static analysis.
4. Step 4 — Staging soak with WordPress integration tests and rollback rehearsal.
5. Step 5 — Production rollout; retain the 1.10.x revert path for one release cycle.
6. Step 6 — Establish a standing cadence to review 2.x patch releases (see Operational Impact).

Operational Impact

Maintenance

• Positive signal: seven patch releases on the 2.x line since v2.0.0 indicates active upstream maintenance — the dominant long-term risk of adopting a fresh major (abandonment mid-line) is materially reduced.
• New standing cost: because upstream publishes only compare links, we now own a recurring internal changelog function for this dependency. Budget a small, recurring review each patch cycle rather than a one-time diff.
• Two supported lines: unchanged — collapse to a single line as fast as rollout allows. Landing on ^2.1.7 rather than ^2.0 shortens the convergence path.
• Dependency hygiene: unchanged — tracking the current Laravel major keeps security patches flowing without forking.

Support

• Note quality remains the weak point, and is now a pattern rather than an incident: v2.0.0 said "based on laravel 12"; v2.1.7 says nothing at all. Support engineers have no triage material.
• Escalation rules unchanged: separate (a) Laravel 12 regressions, (b) package 2.x regressions, (c) legacy plugin type errors before engaging maintainers. Add a fourth bucket: (d) undocumented behavior change from a 2.1.x patch — route to the internal changelog owner first.
• Internal ownership: keep a named owner for the hybrid layer and give that owner the patch-review duty.

Scaling

• Runtime scaling unchanged — no capacity re-planning warranted for a patch bump.
• Upgrade scaling unchanged — Laravel 12 host upgrade, ecosystem audit, and plugin remediation still parallelize well and converge at staging.
• CI scaling: three-version PHP matrix as before; run 8.2/8.4 nightly to contain build-minute cost.
• Patch-cadence scaling: at the observed release rate, a lightweight recurring review (diff composer.json + run static analysis) is sufficient; do not stand up a heavyweight process for patches.

Failure Modes

Ramp-Up

• Engineering: no additional conceptual ramp from this release. v2.1.7 introduces nothing new to learn; the learning load remains the Laravel 11→12 host upgrade and the hybrid-layer audit.
• Effort estimate: unchanged in the large — dominated by the host framework upgrade and ecosystem audit. Directly adopting ^2.1.7 instead of ^2.0 is incrementally cheaper, since it avoids landing on a superseded release and then chasing patches.
• If already on 2.0.x: treat v2.1.7 as a sub-day task (bump, static analysis, regression suite, deploy).
• Documentation: update runbooks to reference ^2.1.7 / Laravel 12 / PHP 8.2 floor; retire the 8.4-only narrative from v1.10.0. Add a short "how we track this dependency's patches" note to close the documentation gap upstream leaves.
• Decision checkpoint (unchanged in substance): if companion packages are not Laravel 12-ready within the planned window, stay on wpstarter/framework ^1.10. The 2.x patch cadence is reassuring but does not unblock an ecosystem that isn't ready.