Grease Laravel Package

Product Decisions This Supports

• Performance-Critical Applications: Justify investment in backend optimizations for high-traffic Laravel apps (e.g., SaaS platforms, e-commerce, or analytics dashboards) where database queries are a bottleneck.
• Tech Debt Reduction: Replace custom query optimizations or legacy caching layers with a maintainable, community-backed solution that now ships explicit correctness guarantees rather than "fast but slightly different" behavior.
• Roadmap Prioritization: Accelerate feature delivery by reducing latency in core workflows (e.g., user dashboards, real-time reporting). v0.9.1 removes a class of hydration edge cases (query-time casting, runtime setTable() on partitioned/archive tables) that previously forced teams to hand-audit or avoid the package on those paths.
• Build vs. Buy: Strengthened in this release. The project now runs a full parity matrix (PHP 8.2–8.5 × Laravel 12/13 + lowest-deps), a whole-instance-state parity test with a tripwire on new Eloquent attribute classes, and weekly CI against upstream. That is QA work you would otherwise fund internally before trusting a query-layer override.
• Upgrade-Policy Decision: v0.9.1 makes the upgrade cadence an explicit product constraint — the package tracks each supported major's current patch line (^12.69.2 || ^13.33). Teams must decide whether "stay current on Laravel patch releases" is an acceptable standing operational commitment.
• Risk Acceptance Decision: This is not a passive dependency. It overrides framework internals and must be re-validated on Laravel patch bumps; the release demonstrates both the risk (upstream drift broke overrides) and the mitigation (parity tests, weekly CI). Treat it as a maintained subsystem, not a drop-in.
• Cost Efficiency: Still MIT-licensed and zero-core-change, but budget a small, recurring slice of platform-engineering time for version tracking instead of a one-time install.

When to Consider This Package

• Adopt if:

  • Your Laravel app relies heavily on Eloquent queries (e.g., >50% of backend logic).
  • You are already on, or can immediately move to, Laravel ^12.69.2 or ^13.33. Composer will not offer 0.9.1 below these floors — plan a composer update within your current major first.
  • You use Model::query()->withCasts([...]), runtime setTable() (partitioned/archive tables), non-$table convention models, #[Refreshes], or GreaseRoutingServiceProvider — these paths were either broken or caveated before and are now parity-tested.
  • You’ve identified slow queries in profiling tools (Laravel Debugbar, Blackfire, Telescope) and suspect Eloquent/query-construction overhead rather than indexing or schema design.
  • You accept a patch-tracking maintenance obligation: someone owns Laravel patch upgrades and re-running the package's tests. Weekly upstream CI means breakage surfaces fast, but only if you're watching.
  • You need Livewire compatibility — now proven through Livewire 4.

• Look elsewhere if:

  • You are pinned to an older Laravel patch line (pre-12.69.2 or pre-13.33) with no near-term upgrade window. There is no supported path on 0.9.1.
  • Your organization requires frozen/minimal-churn dependency upgrades (e.g. regulated environments, long release trains). Overriding framework internals plus a patch-floor requirement is a poor fit for that policy.
  • Your app uses non-Eloquent data access (raw SQL, GraphQL, external APIs) — the optimization surface doesn't apply.
  • Your bottleneck is frontend rendering or network latency, not backend query work (consider Vite, Alpine.js, SSR, CDN).
  • You need vendor SLAs or enterprise support; this remains a community package with a single primary maintainer.
  • Specific upgrade flag: if you use GreaseRoutingServiceProvider on Laravel 12.69.2+, you are exposed to the route() parameter escaping bug (%, ?, # emitted raw, truncating paths). Upgrade is not optional in that configuration.

How to Pitch It (Stakeholders)

For Executives: "Grease is a performance layer for our Laravel backend — a turbocharger for database queries. v0.9.1 is the stabilization release before 1.0: it fixes real correctness bugs (wrong table writes on partitioned/archive data, ignored query-time casts) and adds automated proof that our behavior matches stock Laravel. That converts this from 'a fast package we hope behaves the same' into 'a fast package with a test harness that proves it.' The trade-off is one new operational rule: we stay current on Laravel patch releases. Cost is a small, recurring maintenance line, not a license. Recommend a staging pilot now, with a go/no-go before 1.0."

For Engineering: "v0.9.1 is a correctness release and the last stop before 1.0. Two things to know before we merge it. First, hard floors: Laravel ^12.69.2 || ^13.33 — Composer won't resolve below that, so composer update within our major first. Second, this package overrides framework internals and now deliberately mirrors each major's current patch behavior, so Laravel patch bumps become a re-validation event for us, not a no-op.

What got fixed that matters to us: Model::query()->withCasts([...]) is now applied on greased rows; runtime setTable() on the query's model now carries through to hydrated rows so save()/delete() hit the right table (the old caveat is gone, and convention-named models get their derived table memoized per class, with getTable() overrides called per row as vanilla); #[Refreshes] no longer drops after the first model per class; resolveClassAttribute() cache is property-keyed and reads trait attributes; Request::all() key ordering/collision behavior matches upstream per major.

Action item: if we're running GreaseRoutingServiceProvider on 12.69.2+, upgrade immediately — route() params were emitting %, ?, # raw and truncating URLs.

Test posture is the real story: HasGreaseWholeStateParityTest diffs a greased model's entire instance state against vanilla across cold/warm/hydrated, with a tripwire that fails when Laravel adds a new Eloquent attribute class; CI runs the full matrix (PHP 8.2–8.5 × Laravel 12/13 + lowest-deps) plus a weekly run against latest releases so upstream drift goes red within days. Livewire 4 is now covered. I'll gate the pilot on: our Laravel patch level, a scan for withCasts/setTable/routing-provider usage, and a benchmark against our current caching layer to quantify the actual win."