set_exception_breakpoint
Set breakpoints that pause execution when specific exceptions are thrown during PHP debugging sessions, enabling targeted error analysis.
Instructions
Set a breakpoint that triggers when a specific exception is thrown. Can be set before a debug session starts.
Input 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 |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"exception": {
"default": "*",
"description": "Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException')",
"type": "string"
},
"session_id": {
"description": "Session ID",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/tools/breakpoints.ts:137-217 (registration)Full registration of the 'set_exception_breakpoint' tool, including name, description, input schema, and the complete handler function that manages both pending and active session breakpoints.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 (handler)Low-level handler in DebugSession class that executes the DBGP 'breakpoint_set -t exception' command to set the exception breakpoint and parses the response.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 function to add an exception breakpoint as pending when no active debug session exists.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; }
- Helper code that applies pending exception breakpoints to a new debug session by calling setExceptionBreakpoint.if (bp.exception) { result = await session.setExceptionBreakpoint(bp.exception); applied.push({ pendingId: bp.id, sessionId: session.id, breakpointId: result.id, }); logger.debug(`Applied exception breakpoint ${bp.id} -> ${result.id}`); }