Reference

Change only the defaults your app needs

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

Capture

Set which local environments run and how much evidence is retained.
Store

Choose the profile directory, count limit, and age limit.
Read

Return bounded inspector and MCP views of the retained data.

A read limit does not change what was captured. A capture policy affects only new profiles.

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`	`null`	A local task needs a different setting from Laravel’s debug mode.
`environments`	`['local']`	Your app uses another name for local development.
`theme`	`system`	You want the first visit to start in `light` or `dark` mode.

By default, the package follows APP_DEBUG. Set NEWDEBUGBAR_ENABLED=true or NEWDEBUGBAR_ENABLED=false to override that default. The app must still use an allowed environment. A theme chosen in the browser overrides the starting theme for that browser.

If you already published the configuration, remove any default true value from the enabled setting so it can follow debug mode:

'enabled' => env('NEWDEBUGBAR_ENABLED'),

Tune findings to local work

Thresholds decide when The 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.

Complete setting reference

Keys below are relative to newdebugbar in config/newdebugbar.php. Defaults describe normal local use. Publish the file only when an actual workflow needs a different value.

Key	Type	Default	Runtime effect
`enabled`	Boolean or null	`null`	Null follows `app.debug`. `NEWDEBUGBAR_ENABLED` can explicitly enable or disable profiling, routes, the interface, and MCP within the allowed environments.
`environments`	List of strings	`['local']`	Allows the package to start in the listed Laravel environments.
`theme`	String	`system`	Starting browser theme: system, light, or dark. A saved browser choice takes precedence.
`slow_query_ms`	Number	`100`	Marks slow database queries.
`slow_http_request_ms`	Number	`250`	Marks slow outbound Laravel HTTP calls.
`slow_request_ms`	Number	`1000`	Creates a finding for a slow complete request.
`findings.minimum_cache_operations`	Integer	`5`	Minimum cache reads before a high-miss finding.
`findings.high_cache_miss_rate`	Number	`0.8`	Miss-rate threshold, expressed as a fraction.
`findings.max_findings`	Integer	`50`	Maximum retained findings for a profile.
`storage.path`	String or null	`null`	Null uses storage/framework/newdebugbar in the app.
`storage.max_profiles`	Integer	`20`	Maximum retained profile count.
`storage.max_age_minutes`	Integer	`60`	Profile expiry age.
`mcp.max_items`	Integer	`50`	Maximum items in one bounded MCP page.
`mcp.max_bytes`	Integer	`100000`	Maximum bytes in one MCP response.
`mail_preview.max_body_bytes`	Integer	`50000`	Limit for each retained HTML or text mail body.
`mail_preview.max_attachment_bytes`	Integer	`2000000`	Retained attachment-body budget per message.
`collection.application_path`	String or null	`null`	Null uses the Laravel base path when locating application code.
`collection.max_items_per_collector`	Integer	`500`	Maximum top-level retained records per collector.
`collection.max_items_per_array`	Integer	`100`	Maximum nested array values.
`collection.max_depth`	Integer	`5`	Maximum nested capture depth.
`collection.max_string_length`	Integer	`2000`	Limit for ordinary captured strings.
`collection.query_bindings`	String	`full`	Full, safe, or none. `NEWDEBUGBAR_QUERY_BINDINGS` controls retained binding values.
`collection.key_policy`	String	`full`	Full or hash. `NEWDEBUGBAR_KEY_POLICY` controls cache and Redis key evidence.
`collection.call_sites`	Boolean	`true`	Captures supported application locations and short stacks.
`collection.call_site_frames`	Integer	`5`	Maximum useful application frames retained for a call site.
`collection.call_site_scan_limit`	Integer	`40`	Maximum raw frames scanned to find application frames.
`collection.exception_application_frames`	Integer	`12`	Application frames retained for exception evidence.
`collection.exception_vendor_frames`	Integer	`12`	Framework or package frames retained for exceptions.
`collection.exception_source_context_lines`	Integer	`9`	Source-context window around the exception location.

Verify a configuration change with a new profile

Change one relevant setting, clear cached configuration if necessary, and reproduce the same action. Existing profiles are not rewritten. A missing historical value will not reappear because you raised a limit afterward.

If a client only needs the next part of retained data, use MCP pagination before increasing capture limits. For a missing profile or value, use the focused troubleshooting guide.

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

Capture

Store

Read