Memory Usage Laravel Package

Product Decisions This Supports

• Where to spend performance engineering time. The package logs peak memory per request, scoped by path rules (patterns / ignore_patterns), so we can rank endpoints by measured cost instead of by anecdote. That turns "the app feels slow/heavy" into a prioritized backlog of specific routes.
• Build vs. buy for basic telemetry. It replaces a hand-rolled middleware with a config-driven one that already handles path matching, thresholds, log channel/level selection, and terminable-middleware timing. The build case is weak; the buy case is a Composer require.
• Release regression gating. v5.1.1 fixes peak memory not resetting between matched requests, so per-request comparisons across releases become trustworthy for the first time. Any historical numbers from 5.1.0 are inflated and must be discarded — that is itself a product decision (don't publish dashboards or claims based on them).
• Tiered alerting, not just logging. Because multiple path rules are evaluated independently per request, one path can log a warning at 10 MiB to the default channel and an emergency to Slack at 100 MiB. This gives us a cheap, two-tier early-warning capability without an APM contract — and a concrete decision to make about whether that's enough.
• Slow-response visibility as a bundled second signal. The same paths rule sets carry slow_response_limit, and LogSlowResponse runs from terminate(). So one config buys memory and latency thresholds with per-path routing. Useful for sequencing "is this endpoint heavy, slow, or both?"
• Capacity and cost planning inputs. Route-level peak memory informs worker sizing, queue concurrency, and instance tier. This is directional, not precise — memory_get_peak_usage is process-scoped — so use it to compare routes and releases, not to derive absolute capacity numbers.
• Developer feedback loop. The optional memory-usage response header, gated to configured environments, lets engineers see cost per request locally and in staging without reading logs. Low effort, meaningful reduction in "we didn't know that endpoint was heavy" surprises.
• APM investment justification. If path-scoped memory and slow-response logs answer our questions, we defer a commercial APM purchase. If they don't, we've produced the evidence needed to justify one. Either outcome is a decision, and this package produces it cheaply.

When to Consider This Package

Good fit when:

• The app is Laravel on PHP-FPM, we have no APM or only Pulse/Telescope-level visibility, and we want per-route memory data this quarter.
• We need targeted instrumentation on a handful of suspect endpoints rather than fleet-wide capture — the path matching is the feature, not an afterthought.
• We want per-path thresholds with different log channels and levels (warning vs. emergency, default channel vs. Slack) without wiring an alerting vendor.
• The team can absorb a small interpretive cost: someone must write down what "peak memory" means here, because the number is easy to misread and the 5.1.0 defect proves it.
• We need a dev-only feedback mechanism (response header) alongside production logging.

Look elsewhere when:

• We need distributed tracing, continuous profiling, heap dumps, allocation-level analysis, long-term dashboards, or multi-language coverage. This is request-level signal only.
• We run Octane, Swoole, or long-running workers and cannot verify the peak-reset fix applies there. Under worker reuse, process-scoped peak is exactly the metric that breaks, and it breaks quietly — plausible-but-wrong numbers are worse than none. Treat this as a gating check, not a nice-to-have.
• Request volume is high enough that per-request log lines dominate log spend.
• The output must sit on an on-call alerting path. Community-supported, single-maintainer, no SLA — acceptable for a diagnostic, not for a paging dependency unless we own the wrapper and thresholds.
• We already have a commercial APM with memory graphs; this becomes duplicative and should be scoped to a temporary diagnostic, not a permanent dependency.
• We require structured JSON ingestible by a log aggregator out of the box — verify the emitted format before committing.

Adoption criteria we should apply: pin ^5.1.1 explicitly (never allow 5.1.0 — its matched-request figures are invalid); confirm the Laravel/PHP version matrix against our runtime including config caching; confirm middleware ordering against existing global middleware; confirm the target log channel has retention and rotation configured; assign an internal owner given maintainer concentration. Mitigating factor: the exit path is trivial — removing a middleware and a service provider — so vendor risk is bounded even at 0 GitHub stars.

How to Pitch It (Stakeholders)

To executives: This is a near-zero-cost observability add-on for our Laravel app. It writes per-route memory and slow-response lines to logs we already retain — no new infrastructure, no vendor contract, no schema change. It answers two questions we currently guess at: which endpoints cost the most memory, and did that change with the last release. The latest patch (v5.1.1) fixes a measurement defect, which is why we're adopting now and discarding any earlier trial data. Cost is bounded by log volume, which we control through path scoping rather than capturing everything. It also informs a larger decision: whether we need to buy a full APM platform, and it produces the evidence either way.

To engineering: A Laravel service provider registers two terminable global middleware. Logging happens in terminate(), after the response is sent, so streamed bodies are included and request latency isn't affected by the log write. Configuration is a single published file: paths rule sets with patterns, ignore_patterns, limit (MiB), slow_response_limit (seconds), channel, level, and optional header.environments. Rules evaluate independently, so one path can warn at one threshold and page at another. Pin ^5.1.1 — 5.1.0 accumulates peak memory across matched requests and produces inflated figures. Before rollout, verify reset behavior under Octane/queue workers if we use them, confirm the middleware can't throw into the request path, and confirm we don't silently no-op from an unpublished config or wrong middleware group. Enable on suspect routes first, sampling or path-scoping in production, not global capture on day one.

To product: Route-level memory data lets us sequence performance work by measured impact and validate whether a release actually made things better. It complements — does not replace — a profiling or APM strategy, and it is a diagnostic tool rather than a monitoring product. The one caveat to internalize: these are process-level numbers, so use them for comparison and ranking, never as an absolute per-request cost.