The New Debug Bar

https://newdebugbar.com/docs
Admin
The New Debug Bar is an open-source debugging package for Laravel that captures request profiles,...
Tokens:29,992
Snippets:344
Trust Score:4.7
Update:5 days ago
Show doc for...
Tokens:
Raw
### Direct Redis work example

Source: https://newdebugbar.com/docs/cache-and-redis

In a configured local Redis connection, this short example produces an obvious sequence of SETEX, GET, and DEL commands. The string 'active' or the GET result will not appear as a retained value.

```php
Redis::setex('docs:journey:heartbeat', 60, 'active'); Redis::get('docs:journey:heartbeat'); Redis::del('docs:journey:heartbeat');
```

--------------------------------

### Gather installation versions with php -v and composer show

Source: https://newdebugbar.com/docs/troubleshooting

Run these commands to record PHP and package versions when troubleshooting installation problems. The output helps separate a new failure from an old profile or background request.

```shell
php -v composer show newdebugbar/newdebugbar composer show livewire/livewire php artisan env
```

--------------------------------

### Start MCP server with artisan command

Source: https://newdebugbar.com/docs/troubleshooting/mcp

This command starts the NewDebugBar MCP server as a stdio server. It waits for protocol messages and is normally owned by the client. A waiting terminal is not a successful connection test.

```bash
php artisan mcp:start newdebugbar
```

--------------------------------

### Check package installation and environment with composer show and php artisan env

Source: https://newdebugbar.com/docs/troubleshooting/bar-not-showing

Run from the Laravel application root to verify the package is installed and to see the current environment. The default allowed environment is local; check NEWDEBUGBAR_ENABLED and newdebugbar.environments. A value of false or an environment outside the list disables profiling, package routes, the toolbar, and MCP.

```bash
composer show newdebugbar/newdebugbar php artisan env
```

--------------------------------

### VS Code: Configure MCP server in .vscode/mcp.json

Source: https://newdebugbar.com/docs/mcp

Create `.vscode/mcp.json` in your project with this configuration. Run `MCP: List Servers` from the Command Palette to start the server or inspect its output.

```json
{
  "servers": {
    "newdebugbar": {
      "type": "stdio",
      "command": "php",
      "args": [
        "/absolute/path/to/your-app/artisan",
        "mcp:start",
        "newdebugbar"
      ]
    }
  }
}
```

--------------------------------

### Install Codex plugin for The New Debug Bar

Source: https://newdebugbar.com/docs/mcp

Adds the official plugin to Codex, which starts the MCP server from the Laravel app and provides product guidance. Requires opening the Laravel app's root folder in Codex; no need to publish the config file.

```bash
codex plugin marketplace add newdebugbar/newdebugbar codex plugin add newdebugbar@newdebugbar
```

--------------------------------

### Loop loading days and bookings (N+1 pattern)

Source: https://newdebugbar.com/docs/queries

Loads a trip's days and then loads bookings for each day individually, causing one query per day for bookings. This is the before state in the eight-day example.

```php
$days = $trip->days()->get();  foreach ($days as $day) {     $day->setRelation('bookings', $day->bookings()->get()); }
```

--------------------------------

### Install The New Debug Bar via Composer

Source: https://newdebugbar.com/docs

Install the package as a dev dependency using Composer. Requires Laravel 10+ and PHP 8.1+.

```bash
composer require --dev newdebugbar/newdebugbar:dev-main
```

--------------------------------

### Create InspectWorkspaceCommand

Source: https://newdebugbar.com/docs/artisan

Create this command in a local example app to produce a small command profile with a controlled exit status. Register it through your Laravel version's normal command registration if the app does not discover that directory.

```php
<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;

/** Produces a small command profile with a controlled exit status. */
class InspectWorkspaceCommand extends Command
{
    protected $signature = 'app:inspect-workspace {--fail}';

    protected $description = 'Inspect the local workspace connection';

    public function handle(): int
    {
        DB::select('select 1');
        Log::info('Workspace connection checked.');

        return $this->option('fail') ? self::FAILURE : self::SUCCESS;
    }
}
```

--------------------------------

### Manually add MCP server for The New Debug Bar in Codex

Source: https://newdebugbar.com/docs/mcp

Adds a manual MCP server entry that runs `mcp:start` via the app's artisan file. Replace `/absolute/path/to/your-app/artisan` with the real path. Use this when the Codex version lacks plugin commands.

```bash
codex mcp add my-app-debug-bar -- php /absolute/path/to/your-app/artisan mcp:start newdebugbar
```

```bash
codex mcp list
```

--------------------------------

### Send a test mailable to a fixture recipient

Source: https://newdebugbar.com/docs/mail-and-notifications

After setting the log mailer and clearing cached configuration, send the app's existing mailable to a fixture recipient. JourneyReviewReady and Trip belong to the example app.

```php
Mail::to('elise@example.test')->send(new JourneyReviewReady($trip));
```

--------------------------------

### Docker Compose MCP server configuration for Sail

Source: https://newdebugbar.com/docs/local-environments

Configuration pattern for starting the MCP process inside the application container. Replace the Compose file path and service name with your project's values. Assumes the service's working directory contains artisan and that -T disables a pseudo-terminal for MCP standard input/output.

```json
{
  "command": "docker",
  "args": [
    "compose",
    "--file", "/absolute/path/to/your-app/compose.yaml",
    "exec", "-T",
    "laravel.test",
    "php", "artisan", "mcp:start", "newdebugbar"
  ]
}
```

--------------------------------

### PHP: Catch and report exception with fallback response

Source: https://newdebugbar.com/docs/errors-and-logs

Use this Laravel example to reproduce a failure that is caught and reported while still returning a successful response. The code throws a RuntimeException, reports it, logs a warning with context, and returns a JSON response with a 200 status. The reported failure remains visible in Exceptions and Logs even though the response succeeds.

```php
try {
    throw new RuntimeException('The local partner example is unavailable.');
} catch (RuntimeException $exception) {
    report($exception);

    Log::warning('Using the saved availability result.', [
        'trip_id' => $trip->id,
    ]);
}

return response()->json(['source' => 'saved']);
```

--------------------------------

### Run InspectWorkspaceCommand with and without --fail

Source: https://newdebugbar.com/docs/artisan

Run the command normally to get exit code 0, or with --fail to get exit code 1. The failure case should have exit code 1; the successful case should have exit code 0.

```bash
php artisan app:inspect-workspace
```

```bash
php artisan app:inspect-workspace --fail
```

--------------------------------

### Cursor: Configure MCP server in .cursor/mcp.json

Source: https://newdebugbar.com/docs/mcp

Create `.cursor/mcp.json` in your project with this configuration. Save the file and restart Cursor, then check the server in Customize → MCPs.

```json
{
  "mcpServers": {
    "newdebugbar": {
      "command": "php",
      "args": [
        "/absolute/path/to/your-app/artisan",
        "mcp:start",
        "newdebugbar"
      ]
    }
  }
}
```

--------------------------------

### Laravel view assertion for journeyTitle

Source: https://newdebugbar.com/docs/views

Example of a Laravel view assertion that verifies the view receives the expected 'journeyTitle' value.

```php
get('/trips/kyoto-autumn')
    ->assertOk()
    ->assertViewHas('journeyTitle', 'Kyoto in autumn');
```

--------------------------------

### Corrected controller passes 'journeyTitle' key

Source: https://newdebugbar.com/docs/views

Example of the corrected controller call that aligns the key with the template's expected variable.

```php
return view('trips.summary', ['journeyTitle' => $trip->title]);
```

--------------------------------

### Check PHP runtime and Artisan path

Source: https://newdebugbar.com/docs/troubleshooting/mcp

Run this command to verify the PHP executable and Artisan path used by the MCP client. Replace the absolute paths with your own. A desktop client may not inherit your shell's PHP path, aliases, or environment.

```bash
/absolute/path/to/php -v /absolute/path/to/php /absolute/path/to/your-app/artisan env
```

--------------------------------

### Disable the bar via .env

Source: https://newdebugbar.com/docs/installation

Add this to your .env file to leave the package installed but turn it off. This value takes precedence over debug mode.

```env
NEWDEBUGBAR_ENABLED=false
```

--------------------------------

### Other MCP clients: Add local stdio server

Source: https://newdebugbar.com/docs/mcp

Add a local `stdio` server with this command and these arguments. Your client may store this setting in a different file.

```json
{
  "command": "php",
  "args": [
    "/absolute/path/to/your-app/artisan",
    "mcp:start",
    "newdebugbar"
  ]
}
```

--------------------------------

### Blade template reads 'journeyTitle' variable

Source: https://newdebugbar.com/docs/views

Example of a Blade template expecting a 'journeyTitle' variable, which may not match the controller's 'title' key.

```blade
<h1>{{ $journeyTitle }}</h1>
```

--------------------------------

### Check PHP and Laravel environment in terminal

Source: https://newdebugbar.com/docs/local-environments

Run these commands to compare the PHP version and Laravel environment used by your terminal or client with the runtime context captured by the web request. Use an absolute executable path in the MCP configuration if the per-site PHP selection differs.

```bash
php -v
php /absolute/path/to/your-app/artisan env
```

--------------------------------

### Controller passes title under 'title' key

Source: https://newdebugbar.com/docs/views

Example of a controller returning a view with a 'title' key, which may not match the template's expected variable.

```php
return view('trips.summary', ['title' => $trip->title]);
```

--------------------------------

### Enable profiling in testing environment

Source: https://newdebugbar.com/docs/testing

Publish the package configuration and include 'testing' in the allowed environments array. The New Debug Bar defaults to the local environment and follows APP_DEBUG; enable debug mode or set NEWDEBUGBAR_ENABLED=true in the test environment.

```php
'environments' => ['local', 'testing'],
```

--------------------------------

### Call list-debug-profiles with path fragment

Source: https://newdebugbar.com/docs/artisan

Ask your agent to call list-debug-profiles with a path fragment matching the command. Choose by runtime name, recorded time, and exit code. Read the Request inspector (labeled Runtime for non-HTTP work), then Queries and Logs.

```json
{
  "path": "artisan:app:inspect-workspace",
  "limit": 5
}
```

--------------------------------

### Validate with a named error bag in Laravel

Source: https://newdebugbar.com/docs/validation

Use validateWithBag with a named error bag to validate fields before saving. The example requires 'passport_number' and 'contact_email' with specific rules. Submitting an empty passport number and 'elise-at-example.test' as email should produce Required and Email failed rules.

```PHP
$validated = $request->validateWithBag('traveler-details', [
    'passport_number' => ['required', 'string'],
    'contact_email' => ['required', 'email'],
]);
```

--------------------------------

### Run a worker for the same connection and queue

Source: https://newdebugbar.com/docs/queues

Run a worker for the same connection and queue to process the job. Use the --once flag to process a single job.

```bash
php artisan queue:work database --queue=journeys --once
```

--------------------------------

### Prompt to compare API requests with an agent

Source: https://newdebugbar.com/docs/mcp

Use this prompt to instruct an agent to profile and compare repeated API requests, keeping the exact X-NewDebugBar-Profile ID from each response. It asks for status, server duration, query count and time, and peak memory, and to inspect findings and relevant queries, cache activity, or outgoing HTTP calls.

```text
Profile GET http://your-app.test/api/trips using an HTTP client and The New Debug Bar MCP server. Keep the exact X-NewDebugBar-Profile ID from each response. Compare repeated requests with the same inputs and authentication, separating cold and warm caches. Report status, server duration, query count and time, and peak memory. Inspect findings and the relevant queries, cache activity, or outgoing HTTP calls to explain the expensive work.
```

--------------------------------

### Fake a slow partner HTTP response with Laravel Http::fake

Source: https://newdebugbar.com/docs/performance

Use this in a local example route to simulate a remote partner service that takes about 300 ms, so the delay is visible in the HTTP Client and Timeline inspectors. The fake prevents any real partner request. The exact local duration will vary.

```php
use Illuminate\Support\Facades\Http;

Http::fake([
    'partner.example.test/*' => function () {
        usleep(300_000);

        return Http::response(['available' => true]);
    },
]);

$availability = Http::get('https://partner.example.test/availability')->json();
```

--------------------------------

### Eager loading bookings with with()

Source: https://newdebugbar.com/docs/debugging-with-agents

Replacement code using eager loading to fetch bookings for all days in one query. This reduces the number of booking queries.

```php
$days = $trip->days()->with('bookings')->get();
```

--------------------------------

### Test validation errors with Pest

Source: https://newdebugbar.com/docs/validation

Use Pest's post helper to assert that the named error bag contains errors for the specified fields. The test posts invalid data and checks for session errors with the 'traveler-details' error bag. Ensure you use your app's real route and required setup.

```PHP
use function Pest\Laravel\post;

post('/travelers', [
    'passport_number' => '',
    'contact_email' => 'elise-at-example.test',
])->assertSessionHasErrors(
    ['passport_number', 'contact_email'],
    errorBag: 'traveler-details',
);
```
Tokens:
Raw