Newrelic Laravel Package

Getting Started

Install and verify the New Relic PHP agent before touching the package — the wrapper is only a thin namespaced facade over newrelic_* functions, so if extension_loaded('newrelic') is false nothing else matters.

1. Install the agent (newrelic-install install or your distro package), set newrelic.license, newrelic.appname, and newrelic.enabled in newrelic.ini (or the equivalent env vars), restart PHP-FPM, and confirm with php -m | grep newrelic and a request showing up in the New Relic UI.
2. composer require intouch/newrelic. The package is archived and pinned to a 2019 release, so commit the lockfile and consider a composer.json conflict/replace guard if you later move to an official SDK.
3. Because this package is framework-agnostic (no service provider/auto-discovery), bind it once in a service provider:

// App\Providers\AppServiceProvider::register()
$this->app->singleton(\Intouch\Newrelic\NewrelicInterface::class, function () {
    return new \Intouch\Newrelic\Newrelic();
});

4. First use case: a global middleware that names the transaction and attaches request context, plus a call in App\Exceptions\Handler::report() to noticeError(). That alone gives you useful APM data with two lines of code.

Where to look first: the README's method table (it maps 1:1 to the agent's newrelic_* functions), then the wrapper class itself — it is small enough to read end to end in a few minutes, which is the safest way to confirm which methods actually exist on your pinned version.

Implementation Patterns

Interface + null object for parity. Bind NewrelicInterface to a no-op implementation in local/testing so your application code never branches on whether the agent is present. The wrapper still calls newrelic_* when the extension is missing (they become undefined-function errors on some builds), so the null object is the reliable guard.

Middleware for transaction naming. Name the transaction from the route early — setTransactionName('GET /orders/{order}') — and add addCustomParameter('user_id', ...) and tenant/plan attributes. Keep parameter counts low; New Relic caps custom attributes per transaction.

Exception handler. In Handler::report() call noticeError($e->getMessage(), $e) (or the string-only overload) before the parent call. This is the single highest-value integration and usually replaces a lot of log-scraping.

Queue jobs. Wrap handle() with a background transaction: start the transaction, run the job, endTransaction() in a finally. Without an explicit end, background work is either dropped or mis-attributed to whatever transaction context leaked in.

Custom events / business metrics. Use the wrapper's custom-event and custom-metric methods for domain signals (order placed, payment failed) rather than stuffing everything into custom parameters — events are queryable in NRQL, parameters are not.

Browser timing. Echo the browser timing header as the first thing in your Blade layout, before any other output, and the footer before </body>. Do not route it through a view composer that may run after output has started.

Deploy markers. Call the deployment-recording method from a deploy script or Artisan command so releases line up with error spikes.

Facade alias (optional). If you prefer Newrelic::setTransactionName(...) over injection, register an alias pointing at the same singleton — but injection keeps the null-object swap honest.

Gotchas and Tips

• Archived and unmaintained since 2019. No PHP 8.x-specific fixes and no coverage of newer agent features (distributed tracing headers, OpenTelemetry bridges, newer custom-event limits). Treat it as a frozen dependency and budget for replacing it; the official newrelic/newrelic-php-agent and the New Relic PHP SDK are the forward paths.
• Naming timing. setTransactionName and setAppName only take effect if called before the transaction is finalized. Calling them late in the request silently does nothing.
• noticeError argument shapes. The agent distinguishes string-only from message+exception. Passing an exception as the first argument, or both a string and an exception where only one is accepted, results in a generic error or a dropped notice. Match the wrapper signature exactly.
• Attribute limits. Custom parameter keys collide with New Relic reserved attributes (request.uri, host, etc.) and values are truncated around 255 characters. Large arrays/objects are flattened or dropped — serialize deliberately.
• Config lives in newrelic.ini, not the package. There is no package config file to publish; newrelic.enabled=false turns calls into no-ops but leaves the functions defined, which is easy to misread as "working."
• Output ordering for browser timing. Any echo, BOM, or whitespace before the header breaks RUM injection. In Laravel this often means a stray newline in a service provider or a middleware that writes to the response body before the view renders.
• Background transactions must be closed. Forgetting endTransaction() in a queued job leaks transaction state into subsequent work in long-running workers (Horizon, Octane).
• Debugging. When data does not appear, first check newrelic.daemon.* logs and newrelic.enabled, then verify the agent version supports the function you are calling — the wrapper may expose a method the installed agent does not implement, yielding a fatal "call to undefined function."
• Extension points. The interface is the clean seam: decorate it for sampling, redaction of PII from custom parameters, or per-tenant app names. Because the class is small and final-ish in behavior, a decorator is safer than subclassing; use the __call-style proxying (if present on your version) only after confirming the method maps to an agent function that exists on your installed extension.