Grease Laravel Package

Technical Evaluation

Architecture Fit

• Eloquent-Centric Optimization (unchanged): The package targets Eloquent's hot path (query building, hydration, eager loading), so it fits applications where Eloquent is the dominant data-access path and query/hydration cost is measurable.
• Framework-internals override, not "zero core change" (corrected): The v0.9.1 notes state plainly that "Grease overrides framework internals" and must "mirror its latest vanilla behaviour." It does not fork or patch Laravel, but it is coupled to private-ish behaviour in Illuminate\Database\Eloquent\Model, routing, request input handling, and Blade component attribute bags. Architecture fit remains high for teams that accept a fast-moving dependency tracking upstream patch releases; it is low for teams that treat framework internals as frozen ground.
• Byte-identical output is now a tested invariant, not an assumed one (materially changed): 0.9.1 fixes two real hydration divergences from 0.9.0 — withCasts() being ignored on greased rows, and runtime setTable() on partitioned/archive models producing rows whose save()/delete() targeted the class table. Both were silent data-correctness issues, not performance quirks. The new HasGreaseWholeStateParityTest (cold/warm/hydrated full instance-state comparison, with a tripwire that fails when Laravel adds a new Eloquent attribute class) is the single most important thing in this release for a TPM: it converts "trust us, output is identical" into an executable, CI-enforced claim.
• Version floors move the fit decision (breaking): ^12.69.2 || ^13.33 replaces the prior "Laravel 10.x+" framing. Laravel 10/11 shops are now out of scope entirely, and even Laravel 12 shops must be on a recent patch line, not just the major.

Integration Feasibility

• Low friction at install time, higher friction at upgrade time: Adoption is still a service provider + facade opt-in with no required configuration. The cost has shifted from install to staying current — the package tracks the current patch line of each supported major.
• Dependency constraints (updated):
  • Laravel ^12.69.2 || ^13.33 — Composer will simply not offer 0.9.1 below those floors. Teams must composer update within their major first.
  • PHP 8.2–8.5 (CI matrix), superseding the earlier "PHP 8.1+" statement.
  • Livewire 4 is now covered by the compatibility proof; Livewire 3 remains implied but should be confirmed for your version.
• Routing provider is a distinct, opt-in surface: GreaseRoutingServiceProvider had a URL fast-path defect where %, ?, # were emitted raw, truncating generated paths. Fixed in 12.69.2/13.31-mirroring code. If you run that provider on 12.69.2+, 0.9.1 is a required upgrade, not an optional one — this is the only item in the notes with an explicit "upgrade" instruction.
• Testing overhead (narrower than before, but real): The parity test suite reduces the need for bespoke behavioural regression testing of hydrated model state, and the tripwire gives you a canary when Laravel changes Eloquent internals. You still own regression testing of query-heavy workflows for performance claims, and you should add a test that exercises withCasts(), partitioned/setTable() models, and #[Refreshes] if you use them.
• Pre-1.0 semver: 0.9.1 is explicitly "the last stop before 1.0." Under 0.x semver, minor bumps may break. Pin exact versions and read changelogs until 1.0 lands.

Technical Risk

• Upstream drift is now the primary risk, and it is structural (escalated): Laravel patch releases since 0.9.0 changed several methods Grease overrides — enough to produce two correctness bugs. This is the defining risk profile: a Laravel patch bump can silently change Grease's behaviour. Mitigation is genuinely improved (see guardrails), but the risk class does not go away; it becomes a recurring operational tax.
• Silent correctness over loud failure (new emphasis): Both 0.9.1 bugs manifested as wrong data (ignored casts, writes hitting the wrong table for partitioned models), not exceptions. Any team on partitioned/archive tables or using withCasts() should treat 0.9.0 as unsafe and audit that window.
• Guardrails (new, materially reduces risk):
  • HasGreaseWholeStateParityTest — full instance-state parity across cold/warm/hydrated paths.
  • Attribute-class tripwire — fails the build when Laravel introduces a new Eloquent attribute class, surfacing drift before users do.
  • Weekly CI against latest Laravel releases — drift turns the build red within days rather than at your next upgrade.
  • Full parity matrix: PHP 8.2–8.5 × Laravel 12/13, plus lowest-deps on both floors.
  • These are the difference between "niche package with community maintenance" and "package with a correctness harness." Weight them heavily in the go/no-go.
• Memory tradeoffs (unchanged): Lazy hydration and query batching can raise peak memory on complex queries; the memoized per-class table-name derivation is explicitly designed to "stay cheap," but per-row getTable() overrides (sharded, AsPivot, custom) are called per row as in vanilla — check that against your model counts.
• Maintenance risk (reframed): Still MIT, still a small community, but 0.9.1 shows active, disciplined maintenance (audit → fix → parity test → CI matrix → weekly drift detection). The relevant question is no longer "will it be abandoned?" but "will its release cadence match your Laravel patch cadence?"

Key Questions

1. Laravel patch level: Are we on 12.69.2+ or 13.33+ today, and what is our patch-upgrade cadence? Can we commit to staying on the current patch line per major?
2. Do we run GreaseRoutingServiceProvider? If yes on 12.69.2+, this upgrade is mandatory — what is the rollout window?
3. Do we use withCasts(), runtime setTable() (partitioned/archive tables), #[Refreshes], or trait-based class attributes? These are the exact surfaces 0.9.1 touched; each needs a targeted regression test.
4. Do we rely on Request::all() key ordering or ComponentAttributeBag::merge() style output? Both changed behaviour to match vanilla — snapshot tests on forms/uploads and Blade style defaults should be checked.
5. Did we ship 0.9.0 anywhere? If so, audit for ignored casts and mis-targeted writes/deletes before anything else.
6. Version pinning policy: exact-pin through 1.0, or floating within ^0.9? Who reads the changelog on each bump?

Integration Approach

Stack Fit

• Ideal for: High-throughput read-heavy APIs and SaaS dashboards on Laravel 12.69.2+ or 13.33+; legacy monoliths with bloated Eloquent chains, provided the framework is current; event-driven/queue workloads where hydration dominates; teams already running a weekly dependency-update ritual.
• Poor fit now: Laravel 10/11 estates (no path without a framework upgrade — the earlier "may work on 9.x with minor tweaks" note is obsolete); teams with a slow, quarterly patch cadence; applications that have not yet proven parity on Eloquent-adjacent packages.
• Watch items: GraphQL resolvers (hydration interaction untested by their matrix), Livewire (4 is proven — confirm your version), and any package that overrides Model internals (stancl/tenancy with runtime setTable(), spatie/laravel-activitylog, laravel-nestedset) — the setTable() fix directly implicates tenancy/sharding setups.

Migration Path

1. Stop-the-bleed check (0.9.0 users only): Search for withCasts() usage and any model whose table is set at runtime. Verify hydrated rows write to the correct table. Treat this as a data-integrity audit, not a code review.
2. Framework floor alignment: composer update within your Laravel major to reach 12.69.2+/13.33; confirm PHP 8.2+ (8.2–8.5 supported). Laravel 10/11 requires a framework upgrade project — sequence that separately and do not bundle it with Grease adoption.
3. Pin and stage: Pin Grease to exact 0.9.1 (pre-1.0 semver). Install with optimizations disabled (Grease::disableAll()) in staging; run the existing suite to prove no regression from the dependency alone.
4. Targeted parity validation: Add regression tests for the four touched surfaces — withCasts(), runtime setTable(), #[Refreshes], Request::all() ordering/upload collisions — plus Blade style merge output if you use it.
5. Enable incrementally: non-critical models → high-traffic read endpoints → full. Keep the routing provider enablement as its own flag so a URL-generation issue can be isolated.
6. Canary: 10% of traffic behind a feature flag; compare latency, memory, and error rates before full rollout.

Compatibility

• Laravel: ^12.69.2 || ^13.33. Patch-level floors are enforced by Composer — this is a hard gate, not guidance.
• PHP: 8.2–8.5 (CI-verified). The earlier 8.1 claim should be retired.
• Livewire: 4 covered by the compatibility proof; verify 3.x if that is your version.
• Database drivers: MySQL vs PostgreSQL behaviour is still a per-driver test concern, particularly around hydration and query batching; the partitioned/setTable() fix should be validated on your primary driver and any archive driver.
• Package conflicts: Higher scrutiny needed for anything that mutates Model state or table resolution at runtime (stancl/tenancy, sharding packages, AsPivot implementers) — the 0.9.1 fix makes these work like vanilla, but they are the highest-variance integration surface.

Sequencing

1. Data-integrity audit (0.9.0 exposure only).
2. Laravel/PHP floor alignment and CI matrix update.
3. Exact-pin to 0.9.1; disabled-mode staging run.
4. Targeted parity tests for the four changed surfaces.
5. Feature-flagged enablement by model and endpoint.
6. Canary at 10%, then full — with the weekly upstream-CI signal watched as an early-warning system.

Operational Impact

Maintenance

• Effort: Low at runtime, moderate at upgrade time (revised from "Low" across the board). No configuration to tune; the recurring cost is patch-cadence tracking. Budget roughly a recurring check-in per Laravel patch release, plus a real upgrade task whenever the package raises its floor.
• Upgrade policy: Exact-pin through 1.0; review the CHANGELOG each bump; never let the package lag your Laravel patch line, since it mirrors vanilla behaviour of a specific patch.
• Monitoring: Query latency and memory via Debugbar, Blackfire, or APM. Alert on query duration >500ms and unexpected memory growth on hydrated collections.
• Upstream signal: The package now runs weekly CI against latest Laravel. Track its build status as a leading indicator — red there means a Laravel patch changed something Grease overrides.

Support

• Debugging: Grease::debug() for applied optimizations, Grease::disableFor(Model::class) for per-model isolation. New in this release: the whole-state parity test is a usable template for reproducing a divergence in your own app.
• Version floors as a support boundary: Because 0.9.1 tracks specific patch lines, first-line triage should always start with "what Laravel patch are you on?" Mismatched patch levels are now the most likely root cause of odd behaviour.
• Community: GitHub issues/discussions only; no commercial SLA. The improved CI and parity harness partially substitutes for vendor support — treat it as the de facto quality signal.
• SLA impact: Minimal for opt-in enablement; the one non-negotiable is the routing provider fix for anyone on 12.69.2+.

Scaling

• Horizontal: Net positive — lower per-request DB work directly reduces load per node.
• Vertical: Reduced pressure on DB instance sizing remains a plausible outcome; validate with your own benchmarks rather than assuming.
• Concurrency: Query batching can increase lock contention under high concurrency; load-test at your target RPS.
• Serverless / Vapor: Measure cold-start impact, particularly the memoized per-class table derivation and any per-row getTable() overrides on large result sets.
• Partitioned/sharded tables: 0.9.1 makes writes behave correctly, but per-row getTable() calls on high-cardinality result sets are a scaling cost worth measuring.

Failure Modes

Ramp-Up

• Developer onboarding (30 minutes): how to opt in/out (Grease::enable(), disableFor()), how to read Grease::debug(), and the one rule that matters — check the Laravel patch level before debugging anything else.
• Internal wiki additions: before/after query examples; the supported version floors; known conflict list (tenancy/sharding packages, laravel-nestedset); the changelog-review ritual.
• QA process: performance gates in CI (fail if query time regresses >10%); permanent regression tests for withCasts(), runtime setTable(), Request::all() ordering, and Blade style merging; a documented checklist for each Grease version bump.
• Rollback plan: flip optimizations off globally (Grease::disableAll()) — no schema or data migration to reverse; per-model disable for narrow blast radius; keep the previous pinned version in composer.json history for a one-line revert; for routing-provider issues, disable that provider independently.
• 1.0 watch: this is the last pre-1.0 release. Prepare for a semver-policy change (pin loosening becomes safe at 1.0) and a likely re-read of the compatibility matrix at that point.