Getting started

Change only the defaults your app needs

New Debug Bar works without a published file. Publish the configuration when your local environment, workload, or data policy needs a different runtime effect.

Publish the configuration

php artisan vendor:publish --tag=newdebugbar-config

This creates config/newdebugbar.php. Read the comments beside each value before changing it. After editing cached configuration, run php artisan config:clear.

Control package state and theme

Setting	Default	Change it when
`enabled`	`true`	A local task needs profiling, routes, interface work, and MCP completely inactive.
`environments`	`['local']`	Your app uses another name for local development.
`theme`	`system`	You want the first visit to start in `light` or `dark` mode.

Set NEWDEBUGBAR_ENABLED=false to disable the package without removing it. A theme chosen in the browser overrides the starting theme for that browser.

Tune findings to local work

Thresholds decide when New Debug Bar calls attention to captured work. They do not stop collection.

slow_query_ms defaults to 100.
slow_http_request_ms defaults to 250.
slow_request_ms defaults to 1000.

Choose values that separate normal local noise from work you would investigate. Local timings are useful for comparison, not production latency promises.

Control profile storage

Profiles stay in a private local runtime directory. By default, the package uses storage/framework/newdebugbar, keeps the latest 20 profiles, and removes profiles older than 60 minutes.

'storage' => [
    'path' => null,
    'max_profiles' => 20,
    'max_age_minutes' => 60,
],

Increase retention for a longer local workflow. Keep a custom path private and outside version control.

Bound large profiles

Collection limits keep unusual requests quick to encode, store, render, and return through MCP. The defaults retain up to 500 top-level records per collector, 100 nested values per array, five nested levels, and 2,000 characters per ordinary string.

Application call sites are on by default. The package keeps five useful application frames while scanning up to 40 raw frames to find them below framework internals. Turn call sites off only when you are isolating their cost in an unusual local workload.

Choose how local values are retained

Exact local values make a debugger useful. Query bindings and cache or Redis keys are therefore retained by default within the collection limits.

Set NEWDEBUGBAR_QUERY_BINDINGS=safe to mask string bindings, or none to omit all bindings.
Set NEWDEBUGBAR_KEY_POLICY=hash when stable matching is enough and exact cache or Redis keys should not be stored.

These choices apply when the profile is captured. Changing them later does not rewrite profiles already on disk.

Next step

Review what is stored

See where profiles live, when they are removed, which limits apply, and how value policies affect browser and MCP output.

Open data and privacy