set_exception_breakpoint
Set breakpoints to pause PHP debugging when specific exceptions occur, enabling targeted error investigation during development.
Instructions
Set a breakpoint that triggers when a specific exception is thrown. Can be set before a debug session starts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exception | No | Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException') | * |
| session_id | No | Session ID |
Implementation Reference
- src/tools/breakpoints.ts:149-216 (handler)MCP tool handler for 'set_exception_breakpoint'. Handles input parameters, resolves or creates pending session breakpoint, calls underlying session.setExceptionBreakpoint if session active, and returns JSON-formatted response with success status and breakpoint details.
async ({ exception, session_id }) => { const session = sessionManager.resolveSession(session_id); // If no active session, store as pending breakpoint if (!session) { const pendingBp = pendingBreakpoints.addExceptionBreakpoint(exception); return { content: [ { type: 'text', text: JSON.stringify( { success: true, pending: true, message: 'Exception breakpoint stored as pending - will be applied when a debug session connects', breakpoint: { id: pendingBp.id, type: 'exception', exception, enabled: pendingBp.enabled, }, }, null, 2 ), }, ], }; } try { const breakpoint = await session.setExceptionBreakpoint(exception); return { content: [ { type: 'text', text: JSON.stringify( { success: true, breakpoint: { id: breakpoint.id, type: 'exception', exception, state: breakpoint.state, }, }, null, 2 ), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'Failed to set exception breakpoint', message: error instanceof Error ? error.message : String(error), }), }, ], }; } } - src/tools/breakpoints.ts:140-148 (schema)Zod input schema defining parameters for the tool: 'exception' (string, default '*') and optional 'session_id'.
{ exception: z .string() .default('*') .describe( "Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException')" ), session_id: z.string().optional().describe('Session ID'), }, - src/tools/breakpoints.ts:137-217 (registration)Registration of the 'set_exception_breakpoint' tool using server.tool() within registerBreakpointTools function, including name, description, schema, and handler.
server.tool( 'set_exception_breakpoint', 'Set a breakpoint that triggers when a specific exception is thrown. Can be set before a debug session starts.', { exception: z .string() .default('*') .describe( "Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException')" ), session_id: z.string().optional().describe('Session ID'), }, async ({ exception, session_id }) => { const session = sessionManager.resolveSession(session_id); // If no active session, store as pending breakpoint if (!session) { const pendingBp = pendingBreakpoints.addExceptionBreakpoint(exception); return { content: [ { type: 'text', text: JSON.stringify( { success: true, pending: true, message: 'Exception breakpoint stored as pending - will be applied when a debug session connects', breakpoint: { id: pendingBp.id, type: 'exception', exception, enabled: pendingBp.enabled, }, }, null, 2 ), }, ], }; } try { const breakpoint = await session.setExceptionBreakpoint(exception); return { content: [ { type: 'text', text: JSON.stringify( { success: true, breakpoint: { id: breakpoint.id, type: 'exception', exception, state: breakpoint.state, }, }, null, 2 ), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'Failed to set exception breakpoint', message: error instanceof Error ? error.message : String(error), }), }, ], }; } } ); - src/session/session.ts:184-205 (helper)Core helper method in DebugSession class that implements the DBGP protocol command 'breakpoint_set -t exception -x <exception>', parses response, creates Breakpoint object, and stores in session breakpoints map.
async setExceptionBreakpoint(exception: string = '*'): Promise<Breakpoint> { const response = await this.connection.sendCommand('breakpoint_set', { t: 'exception', x: exception, }); if (response.error) { throw new Error(`Failed to set exception breakpoint: ${response.error.message}`); } const result = this.connection.parseBreakpointSet(response); const breakpoint: Breakpoint = { id: result.id, type: 'exception', state: 'enabled', exception, }; this.breakpoints.set(breakpoint.id, breakpoint); return breakpoint; } - Helper to create and store a pending exception breakpoint when no debug session is active; later applied to session via setExceptionBreakpoint.
addExceptionBreakpoint(exception: string = '*'): PendingBreakpoint { const id = `pending_${++this.breakpointIdCounter}`; const bp: PendingBreakpoint = { id, type: 'exception', exception, enabled: true, createdAt: new Date(), }; this.pendingBreakpoints.set(id, bp); logger.info(`Pending exception breakpoint added: ${id} for ${exception}`); this.emit('breakpointAdded', bp); return bp; - src/tools/index.ts:56-56 (registration)Top-level registration call to registerBreakpointTools within registerAllTools, which includes the set_exception_breakpoint tool.
registerBreakpointTools(server, ctx.sessionManager, ctx.pendingBreakpoints);