# ddless

> A desktop PHP debugging tool that replaces dd(), dump(), and Xdebug with a visual, deterministic debugger.

## Overview

ddless is a standalone desktop application for debugging PHP applications. It intercepts HTTP requests, executes your PHP code with instrumentation, and pauses at breakpoints so you can inspect variables, the call stack, and step through execution line by line.

Unlike Xdebug, ddless does not require PHP extensions, IDE plugins, or complex configuration. It works with any PHP project (7.4+) across Local, Docker, WSL, and SSH remote environments.

Supported frameworks: Laravel, Symfony, CodeIgniter 4, Tempest, WordPress, CakePHP, Yii2, Drupal, and Generic PHP (vanilla PHP or any custom framework).

- Website: https://ddless.com
- Documentation: https://ddless.com/docs
- Download: https://ddless.com/download
- Discord: https://discord.gg/xPtXguDrmC
- Contact: jeffleyd@gmail.com

## Pricing

ddless uses a freemium model:

### Community (Free — forever)
- Local debugging (bare metal PHP)
- Docker and WSL support
- Regular breakpoints
- Dumppoints — evaluate expressions, display results, terminate (like dd())
- Variable inspection (read-only)
- Step In / Step Over / Step Out / Continue
- Method execution (test any class method directly)
- Task Runner (execute PHP code with streaming output and step debugging)
- Code navigation (Ctrl+Click go-to-definition)
- Quick file search and content search
- Multi-session debugging (debug multiple projects simultaneously)
- Console output viewer
- Debug Playground (Beta) — evaluate PHP code in the current debug context with a Monaco editor

### Pro ($8/month or $72/year)
Everything in Community, plus:
- SSH Remote Debugging — debug on remote servers via SSH
- Conditional Breakpoints — pause only when a PHP expression is true
- Logpoints — log messages without pausing execution
- Watch Expressions — monitor PHP expressions evaluated at every breakpoint hit
- Conditional Dumppoints — dumppoints that only fire when a condition is true
- Export & Import Debug Snapshots — save/share debug configurations as .ddless files
- AI Copilot — AI-powered debugging assistant with code search, file reading, and memory (knowledge base)
- AI Copilot in Task Runner — AI code generation from natural language, reads project files, searches code
- Priority Chat with the Creator
- PHPStorm Plugin

## Downloads

Available for:
- Windows (.exe installer, .zip portable)
- macOS (.dmg — arm64 for M1/M2/M3/M4, x64 for Intel)
- Linux (.AppImage, .deb, .rpm)

Download page: https://ddless.com/download

## Why ddless Exists

Developers often fall back to dd(), var_dump(), and error_log() because Xdebug is fragile — it breaks when Docker restarts, requires IDE-specific configuration, and doesn't work reliably across environments. ddless provides a deterministic debugging experience that works every time, regardless of your setup.

## Installation Requirements

### Windows
- Windows 10/11 (64-bit)
- PHP 7.4 or higher (for Local mode)
- Docker Desktop (for Docker mode)
- WSL2 (for WSL + Docker mode)

### Linux
- Ubuntu 20.04+, Debian 11+, Fedora 35+, or equivalent
- PHP 7.4 or higher (for Local mode)
- Docker Engine (for Docker mode)
- GTK3 libraries (usually pre-installed)

### macOS
- macOS 11 (Big Sur) or later
- Apple Silicon (M1/M2/M3/M4) or Intel processor
- PHP 7.4 or higher (for Local mode)
- Docker Desktop (for Docker mode)

## Runtime Modes

DDLess supports four runtime modes. Choose based on how your PHP project runs.

### 1. Local Mode

Use this when PHP is installed directly on your computer.

Setup:
1. Create a new project in DDLess — enter a name, port, and select the framework:
   - Laravel — for Laravel projects (uses the framework bootstrap automatically)
   - Symfony — for Symfony projects (boots the Symfony kernel automatically)
   - CodeIgniter — for CodeIgniter 4 projects (uses the CI4 bootstrap)
   - Tempest — for Tempest PHP projects (boots via Tempest container)
   - WordPress — for WordPress sites (automatic bootstrap via wp-load.php, all plugins and themes available)
   - CakePHP — for CakePHP 4/5 projects (automatic bootstrap, middleware pipeline, TableRegistry ORM)
   - Yii2 — for Yii 2 projects (automatic bootstrap, ActiveRecord ORM, service locator)
   - Drupal — for Drupal 9/10/11 projects (DrupalKernel bootstrap, Entity API, service container)
   - Generic PHP — for vanilla PHP or custom frameworks (optionally set an entry point like public/index.php)
2. Select your project folder (the one containing artisan for Laravel, bin/console for Symfony, spark for CodeIgniter, etc.)
3. Choose Runtime: Local
4. If PHP is not in your system PATH, specify the PHP executable path

Common PHP Paths:
- Windows (XAMPP): C:\xampp\php\php.exe
- Windows (WAMP): C:\wamp64\bin\php\php8.x\php.exe
- Windows (Laragon): C:\laragon\bin\php\php-8.x\php.exe
- Windows (Standalone): C:\php\php.exe
- Linux: /usr/bin/php (usually automatic)
- macOS (Homebrew Apple Silicon): /opt/homebrew/bin/php
- macOS (Homebrew Intel): /usr/local/bin/php
- macOS (MAMP): /Applications/MAMP/bin/php/php8.x/bin/php

When to use: XAMPP, WAMP, MAMP, Laragon, or Laravel Valet users. PHP installed via Homebrew (macOS) or apt/dnf (Linux). Simple local development without containers.

### 2. Docker Mode

Use this when your PHP application runs inside a Docker container.

Setup:
1. Create a new project in DDLess
2. Select your project folder on your computer (the folder mounted into Docker)
3. Choose Runtime: Docker
4. Enter your Container Name (find it with docker ps)
5. Enter the Container Path where your project is mounted (e.g., /var/www/html)

Example docker-compose.yml:
  services:
    app:
      container_name: my-laravel-app
      volumes:
        - ./:/var/www/html

Configure: Container Name: my-laravel-app, Container Path: /var/www/html

When to use: Laravel Sail users. Docker Compose development environments. Any containerized PHP application.

### 3. WSL + Docker Mode (Windows Only)

Use this when you develop on Windows but your project and Docker run inside WSL2.

Setup:
1. Create a new project in DDLess
2. Select your project folder using the WSL path:
   - Via network: \\wsl$\Ubuntu\home\username\my-project
   - Via mapped drive: Z:\home\username\my-project
3. Choose Runtime: WSL + Docker
4. Select your WSL Distribution (e.g., Ubuntu)
5. Enter your Container Name
6. Enter the Container Path

When to use: Windows developers using WSL2 for better Docker performance. Projects stored in the Linux filesystem for speed. Teams mixing Windows and Linux workflows.

### 4. SSH Remote Mode (PRO)

Use this to debug PHP applications running on remote servers.

Setup:
1. Create a new project in DDLess
2. Enter the remote project path (e.g., /var/www/my-app)
3. Choose Runtime: SSH
4. Configure your SSH connection:
   - Host: Server address (IP or hostname)
   - Port: SSH port (default: 22)
   - Username: Your SSH user
   - Authentication: Password or Private Key

SSH Key Authentication (Recommended):

Windows (PowerShell):
  ssh-keygen -t ed25519 -f $env:USERPROFILE\.ssh\ddless_key

Linux/macOS (Terminal):
  ssh-keygen -t ed25519 -f ~/.ssh/ddless_key

Then add the public key to your server's ~/.ssh/authorized_keys.

When to use: Debugging staging or production servers. Remote development environments. Cloud-hosted applications (AWS, DigitalOcean, etc.).

## Debugging Your Application

DDLess intercepts HTTP requests, executes your PHP code with instrumentation, and pauses at your breakpoints so you can inspect variables, the call stack, and step through execution line by line.

There are three ways to debug with DDLess: Direct Request (simple, no browser needed), Proxy Mode (browser debugging with real sessions/cookies), and CLI Debug (debug terminal scripts like artisan commands and PHPUnit).

### Managing Projects

Each project card on the home screen shows:
- Framework badge: "Laravel" (red), "Symfony" (sky blue), "CodeIgniter" (orange), "Tempest" (violet), "WordPress" (blue), "CakePHP" (rose), "Yii2" (cyan), "Drupal" (light blue), or "Generic PHP" (gray)
- Entry point: For Generic PHP projects, hover the info icon on the badge to see the configured entry point
- PHP version: Displayed below the badge when detected
- Status indicator: Green dot when listening, gray when idle

Editing a project: Click the three-dot menu on the project card and select "Edit Project" to change the project name, port, framework, or entry point after creation.

### Direct Request (Postman, curl, Insomnia)

The simplest approach — point any HTTP client directly at the DDLess port.

Step 1: Start the Listener
On the home screen, click the "Listen" button on your project card. The status changes to Listening and DDLess opens the debugger automatically.

Step 2: Set Breakpoints
- In the debugger, open a PHP file from the file explorer on the left
- Click on a line number to add a breakpoint (a red dot appears)
- Click the red dot again to remove it

Step 3: Send a Request
Point your HTTP client to the DDLess listener port (the port you configured for the project):

  curl http://127.0.0.1:YOUR_PORT/api/users

DDLess receives the request, executes the PHP code with your breakpoints, and pauses when a breakpoint is hit.

Step 4: Debug
When execution hits your breakpoint:
- The code editor highlights the current line
- The Variables tab shows all values in the current scope
- Use the debug controls (Continue, Next, Step In, Step Out) to navigate

Best for: Testing specific API endpoints, backend routes, or when you don't need a full browser session.

### Proxy Mode (Browser)

Proxy Mode starts a PHP built-in web server (`php -S`) that instruments your code for debugging while preserving real browser sessions, cookies, and authentication. Unlike Direct Request mode, you browse your application in a real browser with the full debugging experience.

This is ideal when you need to debug with real authentication, sessions, CSRF tokens, or any workflow that requires a browser.

How it works:
  Browser
      |
      v
  php -S (:PORT) — DDLess Debug Server
      |
      +-- Instruments PHP code
      +-- Breakpoints, step debugging, variable inspection
      +-- Sessions, cookies, auth work naturally

Proxy Mode works with all runtime types: Local, WSL, Docker, WSL+Docker, and SSH.

Setup:

Step 1: Start the Listener
On the home screen, click the "Listen" button on your project card. The status changes to Listening and DDLess opens the debugger.

Step 2: Start the Debug Server
Once the listener is running, a thin "Debug Server" bar appears above the main toolbar with the current status (Idle, Starting…, or Running) and two buttons. Click "Start Server" to boot `php -S` in your project's environment.

- For Local, WSL, and SSH projects: a random port is assigned automatically.
- For Docker and WSL+Docker projects: a fixed port is required (since it must be mapped in docker-compose.yml). A dialog will ask you to enter the port on the first start. Add the port mapping to your docker-compose.yml:
    ports:
      - "PORT:PORT"
  The port is saved per-project for reuse, and can be changed later in the "Open Browser" dialog — the debug server restarts on the new port before the browser opens.

When the server starts, the status switches to "Running on :PORT" (e.g., :8234).

Tip: If you don't need the bar (API-only projects), click the X on the right to hide it (only available when the server is stopped). The preference is saved per project. To bring it back, click the small antenna icon that appears next to "Task Runner" in the toolbar.

Step 3: Open Browser
Click "Open Browser" (next to Start Server). The button is enabled once the server is running. A dialog asks for the domain:
- For local projects: defaults to "localhost"
- For SSH projects: enter the production domain (e.g., myapp.example.com)

DDLess launches Chrome with a persistent profile per project. Logins, cookies and bookmarks survive between debug sessions; only the HSTS cache is wiped on each launch (so a domain you have visited in production with HTTPS doesn't force-upgrade your local http://). For SSH projects, Chrome is configured with --host-resolver-rules to map the domain to localhost, so cookies and sessions work as if you were on the real domain.

Step 4: Set Breakpoints and Browse
Set your breakpoints in the debugger, then navigate your application in the browser. When a request hits a breakpoint, DDLess pauses execution and shows the debug state. Use Continue, Next, Step In, Step Out as usual.

When you're done, just click "Back" in the top-left of the debugger — it stops the listener for you and returns to the project list.

How it works per runtime:

- Local: DDLess spawns `php -S 0.0.0.0:PORT` directly with your project's PHP binary.
- WSL: DDLess runs `wsl.exe -d DISTRO env VARS php -S 0.0.0.0:PORT` through the WSL distribution.
- Docker: DDLess runs `docker exec -e VARS CONTAINER php -S 0.0.0.0:PORT` inside the container.
- WSL+Docker (Laravel Sail): DDLess runs `wsl.exe -d DISTRO -- docker exec -e VARS CONTAINER php -S 0.0.0.0:PORT` combining both layers.
- SSH: DDLess starts `php -S 127.0.0.1:PORT` on the remote server via SSH and creates an SSH tunnel (local port → remote port) so the browser connects to localhost.

Important: `php -S` is single-threaded. If your code makes an HTTP request back to itself during the same request (e.g., sync queue jobs calling webhooks on the same app), it will deadlock. Use a queue driver like `database` or `redis` instead of `sync` to avoid this.

Example: Laravel Sail with Docker

Laravel Sail runs in a Docker container. To debug it with DDLess:
1. Add a port mapping in docker-compose.yml: ports: ["6375:6375"]
2. Click "Listen" on the project card
3. In the Debug Server bar, click "Start Server" — enter port 6375 when prompted
4. Click "Open Browser" — enter "localhost" as domain
5. Browse http://localhost:6375 in the launched Chrome — DDLess instruments and debugs your code

### CLI Debug (Terminal)

Debug PHP scripts that run from the terminal — artisan commands, PHPUnit tests, queue workers, migrations, seeders, or any standalone PHP file — with the same breakpoint experience as HTTP requests.

Prerequisites:
- The project must be in Listening mode (click "Listen" on the project card first)
- The .ddless/php-ddless wrapper is automatically created when DDLess scaffolds your project

Usage:
  .ddless/php-ddless [--host=<ip>] <port> <script> [args...]

  # Laravel artisan commands
  .ddless/php-ddless 8001 artisan migrate
  .ddless/php-ddless 8001 artisan test --filter=UserTest
  .ddless/php-ddless 8001 artisan queue:work --once

  # PHPUnit
  .ddless/php-ddless 8001 vendor/bin/phpunit tests/

  # Any PHP script
  .ddless/php-ddless 8001 scripts/import-data.php

  # From inside Docker/WSL — use --host to reach the host machine
  .ddless/php-ddless --host=192.168.0.8 8001 artisan test
  .ddless/php-ddless --host=host.docker.internal 8001 artisan test

The port must match the port configured for your project in DDLess.

Step-by-step:
1. Start the Listener — click "Listen" on the project card
2. Set Breakpoints — open a PHP file in the debugger and click on line numbers
3. Run from Terminal — execute .ddless/php-ddless <port> <command> in your project root
4. Debug — the script output streams to your terminal in real time. When a breakpoint is hit, execution pauses and DDLess shows the debug state in the UI. Use Continue, Next, Step In, Step Out as usual.
5. Finish — when the script finishes, the terminal shows the exit code

Tips:
- Breakpoints are copied at run start — changes in the UI during a run take effect on the next run
- Ctrl+C in the terminal stops the PHP process immediately
- Exit codes are preserved — useful for CI/CD integration
- Multiple simultaneous runs are supported — each gets its own debug session
- Child processes (e.g., PHPUnit spawned by artisan test) also have breakpoints active

Best for: Debugging artisan commands, PHPUnit tests, queue workers, database migrations, seeders, custom CLI scripts, or any PHP that runs from the terminal.

### Debug Controls

| Button       | Shortcut    | What it Does                                                |
|--------------|-------------|-------------------------------------------------------------|
| Continue     | F5          | Run until next breakpoint                                   |
| Next         | F10         | Execute current line, skip into functions                   |
| Step In      | F11         | Go inside function calls                                    |
| Step Out     | Shift+F11   | Exit current function                                       |
| Back         | —           | Leave the debugger; stops the listener automatically        |
| Start Server | —           | Boot/stop `php -S` (in the Debug Server bar above toolbar)  |
| Open Browser | —           | Launch Chrome (enabled when the Debug Server is running)    |

## Working with Breakpoints

### Setting Breakpoints
Click on any line number in the code viewer. A red dot indicates an active breakpoint.

Valid breakpoint locations:
- Variable assignments: $user = User::find($id);
- Method calls: $this->repository->save($data);
- Control statements: if ($user->isAdmin()) {
- Return statements: return $response;
- Global scope code: with "Allow Breakpoints in Global Scope" enabled in Preferences > Debug (experimental)

### Conditional Breakpoints (PRO)
Pause execution only when a condition is true.

How to use:
1. Set a breakpoint on a line (red dot)
2. Click the + button that appears next to the breakpoint
3. Select "Condition" from the dropdown
4. Type a PHP expression (e.g., $id > 5 or $user->role === 'admin')
5. Press Enter or click OK

The breakpoint dot turns amber with a ? icon. Execution only pauses when the expression evaluates to true.

Examples:
- $id > 100
- $user->email === 'john@example.com'
- count($items) > 0
- $request->has('debug')
- $this->status === 'active'
- $this->repository->count() > 10

Tip: You can use $this in conditions when debugging class methods. DDLess automatically binds the object context so $this->property works as expected.

### Logpoints (PRO)
Log messages without stopping execution — like a breakpoint that prints instead of pausing.

How to use:
1. Set a breakpoint on a line (red dot)
2. Click the + button next to the breakpoint
3. Select "Log" from the dropdown
4. Type your message using {expression} placeholders for PHP variables
5. Press Enter or click OK

The breakpoint dot turns blue with a ! icon. When that line executes, the message is evaluated and sent to the Logs tab in the Inspector panel — execution continues without pausing.

Examples:
- User: {$user->name}
- Order total: {$order->total} for {$order->items->count()} items
- Query result: {count($results)} rows
- Status: {$response->getStatusCode()}
- Config path: {$this->configPath}

Key details:
- Expressions inside {...} are evaluated with all variables in the current scope
- $this->property works in class methods — DDLess automatically binds the object context
- A line can have a condition OR a logpoint, never both — they are mutually exclusive
- The input has PHP syntax highlighting (variables in cyan, methods in yellow, strings in orange)
- Log messages appear in the Logs tab of the Inspector panel with timestamp and file:line reference
- Automatic deduplication: If a framework (e.g., Laravel middleware) causes the same logpoint to fire multiple times in rapid succession with the same message, DDLess filters duplicates automatically

### Dumppoints
Evaluate multiple PHP expressions at a line, display results in a modal, and terminate execution — like a visual dd().

How to use:
1. Set a breakpoint on a line (red dot)
2. Click the + button that appears next to the breakpoint
3. Select "Dump" from the dropdown
4. Add PHP expressions using the repeater field (one per row)
5. Click + or press Enter to add more expressions
6. Press OK to confirm

The breakpoint dot turns white with a D indicator. When that line executes, all expressions are evaluated, results are shown in a modal dialog, and the PHP process terminates (exit(0)).

Examples:
- $user
- $order->total
- count($items)
- $this->repository->find($id)
- $request->all()

Key details:
- Dumppoints are a free feature — available to all users (Community and PRO)
- $this->property works in class methods — DDLess automatically binds the object context
- A line can have a condition, a logpoint, a dumppoint, OR a conditional dumppoint — they are mutually exclusive
- The PHP process terminates after the dump (exit(0)) — by design, just like dd()
- Results are shown in a modal with collapsible accordion items and interactive JSON viewer
- Errors (undefined variables, syntax errors) are shown in red per expression

### Conditional Dumppoints (PRO)
Combine a condition with dump expressions — the dump only fires when the condition is true.

How to use:
1. Set a breakpoint on a line (red dot)
2. Click the + button that appears next to the breakpoint
3. Select "Cond. Dump" from the dropdown (PRO only)
4. Enter a PHP condition in the "If" field (e.g., $user->role === 'admin')
5. Add PHP expressions to dump using the repeater field below
6. Press OK to confirm

The breakpoint dot turns amber with a D indicator. When that line executes:
- If the condition is false → execution continues normally (no side effects)
- If the condition is true → expressions are evaluated, results shown in modal, process terminates (exit(0))

Examples:
- Condition: $id > 5 | Expressions: $user, $order->total
- Condition: $request->method() === 'POST' | Expressions: $request->all(), $validator->errors()
- Condition: count($items) > 100 | Expressions: $items, memory_get_usage()

Key details:
- Conditional dumppoints are a PRO feature
- When the condition is false, there is zero overhead — execution continues as if the dumppoint didn't exist
- If the condition throws an exception, execution continues silently (no dump, no crash)
- Results use the same modal as regular dumppoints (DumpResultModal)
- Mutually exclusive with conditions, logpoints, and regular dumppoints

### Watch Expressions (PRO)
Monitor PHP expressions that are automatically evaluated every time a breakpoint is hit.

How to use:
1. Set at least one breakpoint (regular, conditional, or logpoint)
2. Open the Watch tab in the Inspector panel
3. Type a PHP expression in the input field (e.g., $user->name)
4. Press Enter to add it
5. When execution hits any breakpoint, all watch expressions are evaluated and their values are displayed

Examples:
- $user->name
- count($items)
- $order->total * 1.1
- $this->repository
- $this->config['database']
- array_keys($data)

Tip: $this is fully supported in watch expressions when debugging class methods.

Key details:
- Watch expressions require at least one breakpoint to be set — without breakpoints, the Watch tab shows an explanation message
- Works with all breakpoint types:
  - Regular breakpoints: watches evaluated when execution pauses
  - Conditional breakpoints: watches evaluated even when the condition is false (results update without pausing)
  - Logpoints: watches evaluated when the logpoint fires (results update without pausing)
- Double-click an expression to edit it
- Click the X button to remove an expression, or Clear All to remove all
- Objects and arrays are shown in an expandable JSON viewer
- If an expression has a syntax error, the result shows Error: <message> in red

## Inspector Panel

When paused at a breakpoint, the Inspector panel shows detailed execution context.

### Variables Tab

| Section           | Description                                   |
|-------------------|-----------------------------------------------|
| Variables         | Local variables in current scope              |
| Arguments         | Parameters passed to the current function     |
| $this             | Object properties (in class methods)          |
| Constants         | Class constants and enums being used          |
| Static Properties | Static properties of the class                |

- Click on any value to expand/collapse objects and arrays
- Click the copy icon to copy a value to clipboard
- Hover over any variable in the code editor to see its current value in a tooltip

### Stack Tab
Shows the full call stack — click on any frame to navigate to that file and line.

### Console Tab
Displays raw stdout/stderr output from the PHP execution.

### Breakpoints Tab
Lists all active breakpoints across files:
- Regular breakpoints (red)
- Conditional breakpoints (amber) — shows the condition expression
- Logpoints (blue) — shows the log message template
- Dumppoints (white) — shows the dump expressions
- Conditional dumppoints (amber) — shows the condition and dump expressions

Click on any entry to navigate to that file and line.

### Logs Tab
Displays messages from logpoints in real-time:
- Timestamp in HH:mm:ss.ms format
- Clickable file:line reference to jump to the source
- Clear button to reset the list
- Auto-scrolls to the latest message
- Badge shows unread count when you're on another tab

### Watch Tab (PRO)
Displays watch expression values, updated at every breakpoint hit:
- Add expressions via the input field at the top
- Values update automatically when any breakpoint is hit (regular, conditional, or logpoint)
- Objects and arrays displayed in expandable JSON viewer
- Expression errors shown in red
- Double-click to edit, X to remove
- Requires at least one breakpoint to be active

### Playground Tab (Beta)
Evaluate PHP expressions in real-time while paused at a breakpoint. The Playground provides a Monaco code editor on the left and a result panel on the right in a split layout.

How to use:
1. Set a breakpoint in your code and trigger a request
2. When paused, switch to the Playground tab in the Inspector panel
3. Write PHP code in the editor — it starts with `<?php` and `return null;` as a template
4. Press Ctrl+Enter or click Run to evaluate
5. The result appears on the right panel immediately

Tip: while paused, hover a variable in the code editor and click "Send to Playground" in the value tooltip — the Playground opens pre-filled with `return $variable;` (works for `$this->prop`, property chains, and class constants too).

What you can do:
- Access all local variables from the current scope (e.g., `return $user;`)
- Access `$this` properties and methods when inside a class method
- Call any function available in the current context (e.g., `return auth()->user();`)
- Run database queries (e.g., `return \App\Models\User::find(1);`)
- Execute multi-line code with loops, conditionals, and variable assignments
- Use `return` to send a value to the result panel

Result display:
- Objects and arrays are shown in an expandable JSON tree viewer
- Scalar values (strings, numbers, booleans, null) are displayed as text
- Errors are shown in a red box with the error message
- stdout output (echo, print) is shown separately above the result
- Execution duration is displayed in the result header

Blocked functions:
The Playground blocks certain functions before eval and returns a descriptive error instead:
- var_dump, var_export, print_r, dump, dd — "Use a return statement instead — the playground formats values automatically."
- die, exit — "This would terminate the debug session."
- echo, print — "Use a return statement instead."
- header — "Headers cannot be sent during a debug session."

Limitations:
- Only available when paused at a breakpoint
- PHP `use` statements do not work inside eval — use fully qualified class names instead (e.g., `\App\Models\User::find(1)` instead of `User::find(1)`)
- Code execution has a 15-second timeout to prevent infinite loops

## Code Navigation

### Ctrl+Click "Go to Definition"
Hold Ctrl (or Cmd on macOS) and hover over any token in the code. It becomes underlined in blue with a pointer cursor. Click to navigate:

| Token type          | Example              | What happens                                                       |
|---------------------|----------------------|--------------------------------------------------------------------|
| Variable            | $user                | Scrolls to its first assignment or function parameter              |
| Method/Function     | createUser           | Scrolls to function createUser( in the current file                |
| Constant            | MAX_RETRIES          | Scrolls to const MAX_RETRIES in the current file                   |
| Class (short name)  | User                 | Resolves FQCN via use App\Models\User, opens file via classmap     |
| Class (FQCN)        | App\Models\User      | Resolves directly via composer classmap, opens file                |

Multiple matches: If more than one file matches (e.g., User.php exists in multiple directories), a popover appears with all options so you can pick the right one. Press Escape to dismiss.

How resolution works:
1. DDLess parses use statements at the top of the current file to build a name-to-FQCN map
2. The FQCN is resolved to a file path using the Composer classmap (vendor/composer/autoload_classmap.php)
3. If the classmap doesn't have it, DDLess falls back to searching the project file index by filename

### Quick File Search
Press Shift twice quickly (double-tap) to open the quick file search dialog. Start typing a filename — results are fuzzy-matched across your entire project. Click a result or press Enter to open the file.

### Content Search
Press Ctrl+Shift+F (or Cmd+Shift+F on macOS) to open the content search dialog. Type text to search across all project files. Click a result to open the file and jump to the matching line.

### Alt+Click "Open in IDE"
Hold Alt and click any line in the code viewer to open it directly in your configured IDE at that line. Faster than right-click → Open in IDE. Requires an IDE to be set in Preferences → Editor.

The modifier can be changed in Preferences → Shortcuts (options: Alt+Click, Shift+Click, Ctrl+Alt+Click).

### Focus & Sync (Global Hotkey)
Press Ctrl+Alt+D from any application to bring DDLess to the front and immediately reload all open tabs. Useful after editing files in your IDE — no need to wait for the 15-second auto-sync interval.

This is an OS-level global shortcut that works even when DDLess is not focused. Customizable in Preferences → Shortcuts.

All shortcuts are customizable in Preferences.

## Method Execution

Test specific methods directly without making HTTP requests.

### Step 1: Open Method Execute
Click the "Execute Method" button (or use the method list that appears when viewing a PHP file).

### Step 2: Configure
- Mode: Class method or standalone function
- Class: Full class name (e.g., App\Services\UserService)
- Method: Method name (e.g., createUser)
- Parameters: PHP code that returns an array of arguments
- Constructor: PHP code that returns constructor arguments (for classes not resolved via framework DI)

Auto-scaffold: When you select a method, DDLess automatically generates parameter code based on the method's signature and type hints. If the class has a constructor, the constructor code is also auto-generated. The constructor signature is displayed above the editor for reference.

Parameter example:
  <?php
  $data = ['name' => 'John', 'email' => 'john@example.com'];
  $notify = true;

  return [$data, $notify];

Constructor example (auto-generated):
  <?php
  $connection = null; // TODO: create or fetch PDO
  $logger = null; // TODO: create or fetch LoggerInterface

  return [$connection, $logger];

If a method or constructor has no parameters, the scaffold defaults to return [].

### Step 3: Enable Debugging (Optional)
Toggle "Enable Debugging" to pause at breakpoints (including conditional breakpoints and logpoints) during method execution.

### Step 4: Run
Click "Run" to execute. Results appear in the right panel showing:
- Return value (expandable JSON viewer)
- Execution time
- Memory usage

### Saving Presets
Save frequently used test configurations:
1. Set up your method, parameters, and constructor code
2. Click "Save Preset" and give it a name
3. Load saved presets from the dropdown
4. Update or delete existing presets

## Task Runner

Execute arbitrary PHP code directly within your project's context — like running code inside a framework command's handle() method.

The Task Runner opens as a floating panel over the debugger — resize it by dragging its left edge (the width is remembered per project) and close it with the X. It provides a Monaco code editor, streaming output panel, preset management, and an optional floating AI chat window. Your code runs with the full framework bootstrapped automatically:
- Laravel: Eloquent, Facades, service container, etc.
- Symfony: Doctrine, services, dependency injection container
- CodeIgniter: Models, services, helpers via CodeIgniter\Config\Services
- Tempest: Full container with discovery-based resolution
- WordPress: Full WordPress environment — $wpdb, WP_Query, get_posts(), all plugin/theme functions
- CakePHP: Full CakePHP application with ORM, services, and middleware
- Yii2: Full Yii2 application with ActiveRecord, components, and services
- Drupal: Full Drupal environment with entities, services, and database
- Generic PHP: Composer autoload is loaded automatically if available

Opening: From the debugger toolbar, click the Task Runner button (terminal icon). Click it again (or the X) to close.

Writing Code: Write PHP code using $this-> to produce formatted output. The editor provides autocomplete for the output methods and your project classes (resolved from the Composer classmap).

Send code from the debugger: select code in the debug editor and right-click:
- "Send to Task Runner" — inserts the selection into the Task Runner editor (replaces the default buffer, or appends below your existing code)
- "Send to Task Runner with AI" (PRO) — opens a dialog showing the snippet; describe what you want and the AI adapts it into a runnable standalone script (resolving dependencies, using interactive prompts for inputs) and applies it to the editor automatically. Errors are shown inline in the dialog.

Example:
  <?php
  use App\Models\User;
  $users = User::where('active', true)->get();
  $this->info("Found {$users->count()} active users");
  $this->table(
      ['ID', 'Name', 'Email'],
      $users->map(fn ($u) => [$u->id, $u->name, $u->email])->toArray()
  );

Available Output Methods:
- $this->info(string $message) — Green info message
- $this->error(string $message) — Red error message
- $this->warn(string $message) — Yellow warning message
- $this->line(string $message) — Plain text line
- $this->comment(string $message) — Gray comment text
- $this->newLine(int $count = 1) — Empty line(s)
- $this->alert(string $message) — Highlighted alert box
- $this->listing(array $items) — Bulleted list of items
- $this->hr() — Horizontal rule separator
- $this->table(array $headers, array $rows) — Formatted table
- $this->json($data) — Display as collapsible JSON tree
- $this->clipboard(string $text) — Display text with a copy-to-clipboard button
- $this->link(string $url, string $label = '') — Clickable link
- $this->progress($total, $label) — Start a visual progress bar
- $this->advance($step, $label) — Advance the active progress bar (updates in-place)

Timing & Spinner Methods:
- $this->spin(callable $callback, string $label = 'Processing...') — Show a spinner while the callback runs, auto-completes on return or shows error on exception
- $this->time(string $label, callable $callback) — Measure execution time of a callback, displays elapsed time after completion

Chart Builder (fluent API):
- $this->chart() — Returns a DdlessChart builder. Supports line, bar, pie, doughnut, and area chart types.

  Example:
    $this->chart()
        ->bar()
        ->labels(['Jan', 'Feb', 'Mar'])
        ->dataset('Sales', [100, 200, 150])
        ->dataset('Returns', [10, 20, 5])
        ->render();

  Builder methods:
    ->line() / ->bar() / ->pie() / ->doughnut() / ->area() — Set chart type (default: line)
    ->labels(array $labels) — Set X-axis labels (or slice names for pie/doughnut)
    ->dataset(string $label, array $data) — Add a data series (can chain multiple)
    ->render() — Emit the chart to the output panel

Interactive Input Methods (pause execution and wait for user response):
- $this->ask(string $question, $default = null, ?callable $rule = null) — Prompt for text input, returns the answer string
- $this->secret(string $question, ?callable $rule = null) — Prompt for masked password input, returns the answer string
- $this->confirm(string $question, bool $default = false, ?callable $rule = null) — Prompt for yes/no, returns bool
- $this->choice(string $question, array $options, $default = null, ?callable $rule = null) — Prompt to pick from a list, returns chosen value
- $this->anticipate(string $question, array $suggestions, $default = null, ?callable $rule = null) — Text input with filtered suggestion list, returns the answer string
- $this->date(string $question, ?string $default = null, ?callable $rule = null) — Native date picker, returns date string
- $this->datetime(string $question, ?string $default = null, ?callable $rule = null) — Native datetime picker, returns datetime string

Validation Rules: All interactive methods accept an optional $rule callback as the last parameter. The callback receives the user's input and should return true/null to accept, or a string error message to re-prompt. When validation fails, the prompt is re-displayed with the error message — the previous prompt is automatically replaced (not duplicated).

  Example:
    $email = $this->ask('Enter your email:', null, function ($value) {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            return 'Please enter a valid email address.';
        }
        return true;
    });

When code reaches an interactive method, a prompt appears inline in the output panel. ask shows a text input, secret shows a masked input with show/hide toggle, confirm shows Yes/No buttons, choice shows a button for each option, anticipate shows a text input with filtered suggestions, date/datetime show native browser pickers. After the user responds, execution continues with the answer. Multiple sequential prompts are supported. Interactive methods work across all runtime modes including SSH.

File Import (CSV Generator):
Attach external files (CSV, TSV, etc.) to the Task Runner and process them as memory-efficient generators.

How to attach files:
1. Click the "Attach" button (paperclip icon) in the editor toolbar
2. Select a file from the file dialog (CSV, TSV, TXT, or any file)
3. The file appears as a chip below the editor showing filename and size
4. Click the X on a chip to remove the file
5. Attached files persist across sessions (stored in .ddless/sessions/<session-id>/imports/)

Using $this->import():
- $this->import(string $filename, string $delimiter = ',', bool $headers = true, string $encoding = 'auto') — Returns a Generator that yields one row at a time
- When $headers is true (default), the first row is used as array keys (associative array per row)
- When $headers is false, each row is a numeric array
- Encoding auto-detection: handles UTF-8 BOM, Windows-1252, ISO-8859-1 and converts to UTF-8 automatically
- Memory usage is constant regardless of file size (Generator reads one line at a time via fgetcsv)

  Example:
    foreach ($this->import('produtos.csv', ';') as $row) {
        $this->info($row['nome'] . ' - R$ ' . $row['preco']);
    }

  Example with progress:
    $this->progress(1000, 'Importing');
    foreach ($this->import('produtos.csv', ';') as $row) {
        // process row...
        $this->advance();
    }

  Example without headers:
    foreach ($this->import('data.csv', ',', headers: false) as $row) {
        $this->line($row[0] . ' | ' . $row[1]);
    }

CSV Export:
Export large datasets to CSV files with chunked streaming. Data is written incrementally to a temp file — no memory limits.

- $this->export(string $filename, callable $callback, string $delimiter = ';') — Stream data to a CSV file in chunks

The callback receives a $page parameter (0, 1, 2, ...) and must return an array of rows. Return an empty array, null, or false to finish the export. Headers are extracted automatically from the keys of the first row. The .csv extension is appended automatically if missing. Default delimiter is ; (Excel-friendly).

  Example:
    $this->export('users', function ($page) {
        return User::orderBy('id')
            ->offset($page * 500)
            ->limit(500)
            ->get()
            ->toArray();
    });

  Example with custom delimiter:
    $this->export('products', function ($page) {
        return Product::offset($page * 1000)
            ->limit(1000)
            ->get(['id', 'name', 'price'])
            ->toArray();
    }, ',');

Value encoding: arrays and objects are converted to JSON, null becomes empty string, booleans become 1/0. The file includes a UTF-8 BOM for Excel compatibility.

While exporting, a progress card shows the filename and row count updating in real time. When complete, a green card appears with a Download button that opens a native Save As dialog. Clicking Stop during an export cancels it cleanly and releases the temp file.

Running: Click Run to execute. Output streams in real time. Click Stop to cancel mid-execution.

Presets: Save frequently used scripts per project. Click Save/Save As to create presets. Presets persist across sessions.

Runtime Compatibility: Works with all modes — Local, Docker, WSL, WSL+Docker, and SSH (PRO).

### Debugging Task Runner Code (Step Debug)

Set breakpoints directly on the code you write in the Task Runner and step through it — same engine as HTTP debugging, with the framework fully bootstrapped.

How to use:
1. In the Task Runner toolbar, click the "Debug" button (bug icon) to enable debugging
2. If breakpoints are currently set on project files, a confirmation modal appears — enabling Task Runner debugging clears the current breakpoint set (one breakpoint context at a time)
3. The editor switches to the debug viewer (read-only) — click line numbers to set breakpoints on your task code
4. Click Run — execution pauses at your breakpoints, with the current line highlighted in the Task Runner editor
5. Use the debug controls as usual: Continue (F5), Next (F10), Step In (F11), Step Out (Shift+F11)
6. Hover variables in the task code to inspect their values while paused

Key details:
- Supported breakpoint types: regular breakpoints, dumppoints, conditional breakpoints (PRO), and conditional dumppoints (PRO). Logpoints are not available in the Task Runner.
- While debugging is enabled the editor is read-only — toggle Debug off to edit the code (your code is preserved)
- Task Runner breakpoints are ephemeral: they are cleared when you disable debugging or close the Task Runner, and the toggle always starts off when you open it
- Works on all runtimes: Local, WSL, Docker, WSL+Docker, and SSH (PRO)
- Stepping into project files works too — the code you call (services, models) is instrumented like any debug session

### AI Copilot in Task Runner (PRO)

An AI-powered code generation assistant integrated into the Task Runner. Describe what you want to test or explore in natural language, and the AI generates ready-to-run PHP code.

Opening: Click the "AI Copilot" button in the Task Runner output header. Requires a PRO license — free users see an upgrade prompt.

How it works:
1. Describe what you want (e.g., "list all users with expired subscriptions")
2. The AI generates complete, ready-to-run PHP code using the Task Runner API
3. Click "Accept" to apply the code to the editor, or "Reject" to dismiss
4. Click "Run" to execute

Key capabilities:
- Generates flat procedural PHP code (no classes) that uses $this-> for output, prompts, charts, etc.
- Can read project files: the AI uses <<FILE:path>> markers to fetch file contents automatically
- Can search code: the AI uses <<SEARCH:query>> markers to search across the project for functions, classes, or any text
- Search uses the file index (built on page load) and file cache for fast results
- After receiving search results or file contents, the AI continues generating accurate code based on real project code
- Never hardcodes data — uses interactive prompts ($this->ask(), $this->date(), $this->choice(), etc.) so generated code is reusable
- Analyzes execution errors and generates corrected code
- Supports multiple markers per response (both SEARCH and FILE together)
- Up to 6 automatic follow-ups per message for file/search resolution
- Helper functions are allowed (function myHelper() {}) but $this is not available inside them

Chat features:
- Chat history saved per project (separate from debug copilot)
- Streaming responses with real-time display
- Visual indicators for search (amber) and file reading (green) operations
- <<FILE:path>> rendered as green badges, <<SEARCH:query>> as amber badges
- Smart auto-scroll (pauses if you scroll up to read, resumes on new message)
- Code blocks with Accept/Reject buttons for applying suggestions to the editor

The AI follows the same language as the developer (Portuguese, English, etc.) and keeps explanations concise (1-2 sentences).

Uses the same AI provider configuration as the debug AI Copilot (Preferences > AI Copilot).

## AI Copilot (PRO)

An AI-powered debugging assistant that analyzes your debug session and helps you investigate bugs.

### Getting Started
1. Configure the AI provider in Preferences > AI Copilot
2. Start a debug session and trigger a request
3. Open the Copilot panel (bottom-right, sparkle icon)
4. Ask questions about your debug session

The Copilot automatically has access to:
- Current breakpoint hit history (variables, call stack)
- Logpoint messages
- Dumppoint results (last dump expressions and values)
- Active conditional dumppoints (condition + expressions per file/line)
- Watch expression values
- Code around breakpoints
- HTTP request details
- Console output

### Interactive Features

Breakpoint Suggestions:
The AI can suggest breakpoints to add. These appear as red clickable buttons with the filename and line number. Click to add the breakpoint to your session.

Watch Suggestions:
The AI can suggest watch expressions. These appear as blue clickable buttons with the expression. Click to add the expression to your Watch tab.

File Requests:
When the AI needs to see code that isn't around your breakpoints, it can request files. The content is fetched automatically (up to 6 follow-ups per response) and provided to the AI for analysis — you'll see a compact green indicator in the chat.

Code Search:
The AI can search across all PHP files in your project to find where a class, function, or method is defined. This appears as an amber pill in the chat. Useful when the AI doesn't know the exact file path.

Memory (Knowledge Base):
The AI has a persistent memory system that stores debug solutions tied to specific files. It works in two ways:

Saving: After resolving a bug, click the "Memory" button in the chat header. A draggable modal opens showing the related PHP files from your context (open tabs, breakpoints, trace, files mentioned in chat). Deselect any that aren't relevant, describe the solution, optionally click "Format with AI" to clean up your description, and save. The memory is stored locally in SQLite.

Recalling: When you start a new conversation, the AI automatically checks if any saved memories match the files you're currently debugging. If relevant memories exist, the AI references them naturally in its response with a clickable purple card. Click the card to view the full memory, edit the solution, or delete it.

On-Demand Search: If you ask the AI "do you have anything in memory about this?", it can search the knowledge base and surface relevant past solutions.

Export: When exporting a debug snapshot (.ddless file), you can optionally include all Copilot memories. When someone imports the snapshot, the memories are imported too.

### Debug Rounds
When you make a new HTTP request during a debug session, a round marker appears in the chat (e.g., "Round 2: POST /api/users") to visually separate different debug rounds.

### Chat Controls
- Clear: Remove all messages from the chat
- Stop: Cancel the AI's response while it's streaming
- Enter: Send a message (Shift+Enter for new line)

Chat history is automatically saved per project and persists across sessions.

### AI Providers & Configuration

DDLess supports three AI providers for the Copilot. All use streaming responses — the AI's answer appears word-by-word in real time, and you can click Stop to cancel at any point.

#### OpenAI
Works with the official OpenAI API and any OpenAI-compatible endpoint (e.g., Azure OpenAI, OpenRouter, LiteLLM).

- Provider: OpenAI
- API Key: Your OpenAI API key (starts with sk-)
- Model: gpt-4o, gpt-4o-mini, gpt-4-turbo, or any model available on your account
- Endpoint (optional): Default: https://api.openai.com/v1/chat/completions

Custom Endpoint: If you use Azure OpenAI or a compatible proxy, enter the base URL. DDLess automatically appends /v1/chat/completions if the URL doesn't already end with it.

Examples:
- OpenRouter: https://openrouter.ai/api
- Azure OpenAI: https://your-resource.openai.azure.com/openai/deployments/your-deployment
- LiteLLM proxy: http://localhost:4000

#### Anthropic
Works with the official Anthropic Messages API.

- Provider: Anthropic
- API Key: Your Anthropic API key (starts with sk-ant-)
- Model: claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001, or any model available on your account
- Endpoint (optional): Default: https://api.anthropic.com/v1/messages

Technical detail: DDLess automatically separates the system message from conversation messages, as required by the Anthropic API format. The anthropic-version: 2023-06-01 header is sent automatically.

#### Ollama (Local)
Run AI models locally on your machine — no API key needed, no data sent to external servers.

- Provider: Ollama
- API Key: (leave empty)
- Model: llama3.1, codellama, mistral, deepseek-coder, or any model you've pulled
- Endpoint (optional): Default: http://localhost:11434

Setup:
1. Install Ollama from ollama.com
2. Pull a model: ollama pull llama3.1 (or ollama pull deepseek-coder for code-focused tasks)
3. In DDLess Preferences > AI Copilot, select Ollama and enter the model name
4. Leave API Key empty and Endpoint as default (unless Ollama is running on a different port)

Model recommendations for debugging:
- llama3.1:8b (~4.7 GB) — Quick responses, basic debugging help
- llama3.1:70b (~40 GB) — Deeper analysis (requires 48+ GB RAM)
- deepseek-coder:6.7b (~3.8 GB) — Code-focused, good for PHP analysis
- codellama:13b (~7.4 GB) — Balanced code understanding

### Streaming Architecture

All three providers use Server-Sent Events (SSE) or NDJSON streaming:

  User sends message -> Electron builds request -> Provider API
                                                       |
                                                       v
                                               Stream starts
                                                       |
      UI updates in real-time  <-- copilot:stream-chunk (each text chunk)
                                                       |
      Response complete        <-- copilot:stream-done  (stream finished)

- Only one stream can be active at a time — starting a new request cancels the previous one
- If you click Stop, the stream is aborted gracefully and any partial response is preserved
- Network errors are caught and displayed as error messages in the chat

## Export & Import Debug Snapshots (PRO)

Save your entire debug configuration as a .ddless file and share it with colleagues or reload it later.

### Exporting
1. Click the Export button in the top toolbar
2. Enter a title (required) and an optional description
3. Click Export — the system save dialog opens
4. Choose a location and save the .ddless file

The snapshot includes: all open tabs, the active file, breakpoints, conditional breakpoints, logpoints, dumppoints, conditional dumppoints, watch expressions, and the serialize depth setting. Optionally, you can check "Include Copilot Memories" to export all saved debug solutions from the AI memory.

### Importing
1. Click the Import button in the top toolbar (available after file indexing completes)
2. Select a .ddless file from the system open dialog
3. All debug configuration is restored — tabs open, breakpoints are set, watches are loaded

Key details:
- The .ddless format uses relative file paths, so snapshots work across different machines and runtime modes (local, Docker, WSL, SSH)
- Importing replaces the current debug configuration
- If the snapshot includes Copilot memories, they are imported into the project's local knowledge base
- A team member can export their debug setup, commit the .ddless file or share it directly, and anyone can import it to reproduce the exact same debugging scenario

## Preferences

Access preferences via the menu bar: DDLess > Preferences (Ctrl+, on Windows/Linux, Cmd+, on macOS).

The Preferences dialog has three tabs on the left sidebar:

### Shortcuts Tab
You can reassign the shortcuts for Quick File Search, Content Search, Focus & Sync, and Open in IDE:
1. Open Preferences
2. Select the Shortcuts tab
3. Click on the current shortcut (e.g., Shift+Shift)
4. The button starts pulsing with "Press keys..."
5. Press the new key combination you want
6. The shortcut is saved immediately

Click Reset to restore the default.

| Shortcut                 | Default         | Description                                                                          |
|--------------------------|-----------------|--------------------------------------------------------------------------------------|
| Quick File Search        | Shift+Shift     | Open fuzzy file search across the project                                            |
| Content Search           | Ctrl+Shift+F    | Search text content across all project files                                         |
| Focus & Sync (Global)    | Ctrl+Alt+D      | Bring DDLess to front and reload all open tabs — works even when DDLess is not focused |
| Open in IDE (Click)      | Alt+Click       | Click any line to open it in your configured IDE. Options: Alt+Click, Shift+Click, Ctrl+Alt+Click |

### Debug Tab

Variable Serialize Depth: Controls how many levels deep objects and arrays are serialized when a breakpoint is hit. Adjust with the slider (range: 1–15).

| Value       | Effect                                            |
|-------------|---------------------------------------------------|
| Low (1–3)   | Faster, shows only top-level properties            |
| Default (4) | Good balance for most projects                     |
| High (5–15) | Captures deeply nested data, may be slower         |

This setting is saved per-project in breakpoints.json and also persisted globally in Preferences.

#### Experimental: Allow Breakpoints in Global Scope

By default, DDLess only instruments code inside functions, methods, and closures. Enable this option to also set breakpoints on PHP code outside of functions — useful for mixed HTML/PHP files commonly found in WordPress themes, Joomla templates, and vanilla PHP projects.

When to enable: If your PHP files contain code at the top level (not inside any function or class method), such as inline <?php ... ?> blocks, global assignments, switch statements, or control structures mixed with HTML.

Limitations:
- Lines that start with HTML tags (e.g., <div>, <p>) are not instrumentable — only lines starting with <?php or pure PHP code
- Short echo tags (<?= ... ?>) are not instrumentable
- case and default labels inside switch blocks are not instrumentable (PHP 8+ restriction) — but code inside each case is

This setting is disabled by default and marked as Experimental. It does not affect debugging inside functions and methods, which works normally regardless of this setting.

### AI Copilot Tab (PRO)
Configure the AI debugging assistant:
1. Provider: Choose between OpenAI, Anthropic, or Ollama (local)
2. API Key: Enter your API key (not required for Ollama)
3. Model: Select the AI model to use
4. Endpoint (optional): Custom API endpoint URL (for Ollama or proxy setups)

Click Save to apply the settings. The button shows a green "Saved" confirmation for 2 seconds.

## PRO Features Summary

### Community (Free)
- Local, WSL, and Docker debugging
- Regular breakpoints
- Dumppoints — evaluate expressions, display results, terminate (like dd())
- Variables inspection (read-only)
- Step In / Step Over / Step Out
- Method execution
- Task Runner — execute PHP code with streaming output and step debugging (breakpoints on your task code)
- Code navigation (Ctrl+Click)
- Quick file search and content search
- Multi-session debugging (debug multiple projects simultaneously)
- Debug Playground (Beta) — evaluate PHP code in the current debug context with a Monaco editor

### PRO
Everything in Community, plus:
- SSH Remote Debugging — debug on remote servers via SSH
- Conditional Breakpoints — pause only when a condition is true
- Logpoints — log messages without pausing execution
- Conditional Dumppoints — dumppoints that only fire when a condition is true
- Watch Expressions — monitor PHP expressions at every breakpoint hit
- AI Copilot — AI-powered debugging assistant with code search, file reading, memory (knowledge base), and interactive suggestions
- AI Copilot in Task Runner — generate PHP code from natural language, with project file access and code search
- Export/Import Debug Snapshots — save and share debug configurations as .ddless files (optionally with Copilot memories)

## Platform-Specific Notes

### Windows

Installation:
- Installer: Run the .exe installer as Administrator for system-wide installation
- Portable: Extract the .zip version to any folder for portable use
- Install Location: Default is C:\Users\{user}\AppData\Local\Programs\DDLess

Docker Desktop:
- Ensure WSL 2 backend is enabled in Docker Desktop settings
- For WSL + Docker mode, enable integration with your WSL distro in Docker Desktop > Settings > Resources > WSL Integration

WSL Configuration — Map as network drive:
  net use Z: \\wsl$\Ubuntu /persistent:yes

### Linux

Installation:

Debian/Ubuntu (.deb):
  sudo dpkg -i ddless_x.x.x_amd64.deb
  sudo apt-get install -f

Fedora/RHEL (.rpm):
  sudo rpm -i ddless-x.x.x.x86_64.rpm

AppImage (Universal):
  chmod +x DDLess-x.x.x.AppImage
  ./DDLess-x.x.x.AppImage

PHP Installation:
  sudo apt update
  sudo apt install php-cli php-mbstring php-xml php-curl

Docker without sudo:
  sudo usermod -aG docker $USER
  newgrp docker

### macOS

Installation:
1. Download the .dmg file
2. Open the DMG and drag DDLess to Applications folder
3. First launch: Right-click DDLess > Open (to bypass Gatekeeper)

Alternative via Terminal (if Gatekeeper blocks):
  xattr -cr /Applications/DDLess.app

| Chip              | File to Download            |
|-------------------|-----------------------------|
| M1, M2, M3, M4   | DDLess-x.x.x-arm64.dmg     |
| Intel             | DDLess-x.x.x-x64.dmg       |

PHP Installation (Homebrew):
  brew install php

## Troubleshooting

### "PHP not found"
Specify the full path to your PHP executable in project settings.
Find PHP location:
- Windows: where php
- Linux/macOS: which php

### "Container not found"
- Ensure Docker is running
- Verify container name with docker ps
- Use the exact container name or ID

### "Breakpoints not working"
Checklist:
1. Listener is running (status shows Listening)
2. Breakpoint is set (red dot visible on the line number)
3. Your request actually executes that code path
4. If using Proxy Mode: ensure the Debug Server is running (status shows "Running on :PORT" in the Debug Server bar) and the browser was launched via "Open Browser"
5. Try clicking Back to return to the project list, then Listen again to restart the listener

### Proxy mode: nothing being debugged
If the Debug Server is running but breakpoints are not hitting:
1. Ensure the Debug Server is running — the bar above the toolbar should show "Running on :PORT" with a green dot
2. Make sure you are browsing through the Debug Server port (shown in the bar), not your app's original port
3. Verify breakpoints are set on lines that your request actually executes

### Proxy mode: request hangs after Continue
If the browser hangs waiting for a response after you click Continue at a breakpoint:
- Most likely cause: your code makes an HTTP request back to itself (e.g., sync queue job calling a webhook on the same app). The php -S server is single-threaded and cannot handle a second request while the first is still running.
- Fix: Change QUEUE_CONNECTION from "sync" to "database" or "redis" in your .env file.
- This is a limitation of PHP's built-in server, not DDLess.

### Proxy mode: Docker port not accessible
If the browser cannot connect to the Debug Server when using Docker:
- Docker requires port mappings in docker-compose.yml. Add: ports: ["PORT:PORT"]
- The port must match the one you entered in the port dialog when starting the Debug Server.
- Random ports do not work with Docker — use a fixed port.

### "Chrome not found" (Open Browser button)
DDLess searches for Chrome in standard installation paths. If it's not found:
- Windows: Ensure Chrome is installed in Program Files\Google\Chrome\Application\ or available via where chrome
- macOS: Ensure Chrome is at /Applications/Google Chrome.app
- Linux: Ensure google-chrome, google-chrome-stable, or chromium is in your PATH

### "SSH connection failed"
- Verify you can connect manually: ssh user@host
- Check your SSH key has correct permissions (600 on Linux/macOS)
- Ensure the server allows your SSH key or password
- Try a different port if 22 is blocked

### "Permission denied" (WSL + Docker)
Files created by Docker may have Linux permissions that Windows can't modify.
1. Stop the listener
2. In WSL terminal, delete the debug folder:
   rm -rf /path/to/project/.ddless/sessions/
3. Restart the listener and set breakpoints again

## Keyboard Shortcuts

| Action                    | Windows/Linux    | macOS            |
|---------------------------|------------------|------------------|
| Continue                  | F5               | F5               |
| Next (Step Over)          | F10              | F10              |
| Step In                   | F11              | F11              |
| Step Out                  | Shift+F11        | Shift+F11        |
| Quick File Search         | Shift+Shift      | Shift+Shift      |
| Content Search            | Ctrl+Shift+F     | Cmd+Shift+F      |
| Focus & Sync (Global)     | Ctrl+Alt+D       | Ctrl+Alt+D       |
| Open in IDE               | Alt+Click        | Alt+Click        |
| Preferences               | Ctrl+,           | Cmd+,            |

## FAQ

### Is DDLess really free?
Yes. Breakpoints, step debugging, variable inspection, Task Runner, Method Execution, CLI Debug, Dumppoints, Proxy Mode, and multi-session debugging are all free forever for local development. No trial, no time limit, no catch.

### What does Pro unlock that Free doesn't?
Pro gives you SSH remote debugging so you can debug staging and production servers, conditional breakpoints to pause only when specific conditions are true, logpoints to log without pausing, watch expressions to monitor values across hits, AI Copilot with code search, file reading, and a persistent memory system that remembers past debug solutions, AI Copilot in the Task Runner that generates PHP code from natural language with project file access, and export/import snapshots (optionally with AI memories) to share debug configs with your team.

### I debug on Docker/WSL. Do I need Pro?
Docker and WSL work on the free plan. But if you debug on remote servers via SSH — staging, production, or CI environments — that's where Pro's SSH remote debugging becomes essential. One production bug caught early pays for a year of Pro.

### How does DDLess compare to Xdebug + Tinkerwell + Ray?
DDLess replaces all three. Xdebug requires a PHP extension and IDE configuration. Tinkerwell is a paid REPL ($49/yr). Ray requires code changes ($49/yr). DDLess gives you step debugging, code execution, and dump logging in one desktop app — starting at $0. See the full comparison.

### Is DDLess an IDE replacement?
No. DDLess works alongside VS Code, PhpStorm, or any editor. It handles the execution and debugging runtime — you keep writing code where you're comfortable.

### Can I cancel Pro anytime?
Yes. Cancel anytime from your dashboard. Your Pro features stay active until the end of the billing period, then you automatically fall back to Free — no data lost, no disruption.

## Links

- Website: https://ddless.com
- Download: https://ddless.com/download
- Documentation: https://ddless.com/docs
- Privacy Policy: https://ddless.com/privacy
- Discord Community: https://discord.gg/xPtXguDrmC