---
title: "corestack_php_xdebug_set"
url: https://docs.corefinity.com/mcp/tools/corestack_php_xdebug_set
type: tool
last_updated: 2026-11-13
feature: php-settings
related:
  - https://docs.corefinity.com/api/reference/runtime/update-php-runtime.md
  - https://docs.corefinity.com/guides/sites/software-and-services/php-settings-and-php-ini.md
---
# corestack_php_xdebug_set

**Set up Xdebug.** Turn Xdebug on (with its modes, start_with_request and IDE key) or off on a non-production row, at corestack_php_runtime_get's `version`; now or tonight. Scope: write. Long-running: answers with a task.

- Scope: `write`
- Runs as a task: yes

## When to use it

Turn Xdebug on (with its modes, start_with_request and IDE key) or off on a non-production row, at corestack_php_runtime_get's `version`; now or tonight.

## Inputs

- `site_id` (integer, ≥ 1, required): The row: a non-production site or environment.
- `enabled` (boolean, required): true turns debugging on with `mode`; false turns it off.
- `mode` (array of one of `develop`, `coverage`, `debug`, `gcstats`, `profile`, `trace`, up to 6 items): xdebug.mode, one or more, e.g. ["debug"]; needed when enabled.
- `start_with_request` (one of `trigger`, `yes`): trigger (the default) or yes.
- `idekey` (string, pattern `^[A-Za-z0-9_.-]{1,64}$`): The IDE key; PHPSTORM when left out.
- `version` (integer, ≥ 0, required): corestack_php_runtime_get's `version`: a change made since is refused `stale`.
- `apply` (one of `now`, `tonight`, default `"now"`): now (the default), or tonight in the row's maintenance window.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "apply": {
      "default": "now",
      "description": "now (the default), or tonight in the row's maintenance window. window: the row's next maintenance window (tonight is kept as its alias).",
      "enum": [
        "now",
        "window",
        "tonight"
      ],
      "type": "string"
    },
    "enabled": {
      "description": "true turns debugging on with `mode`; false turns it off.",
      "type": "boolean"
    },
    "idekey": {
      "description": "The IDE key; PHPSTORM when left out.",
      "pattern": "^[A-Za-z0-9_.-]{1,64}$",
      "type": "string"
    },
    "mode": {
      "description": "xdebug.mode, one or more, e.g. [\"debug\"]; needed when enabled.",
      "items": {
        "enum": [
          "develop",
          "coverage",
          "debug",
          "gcstats",
          "profile",
          "trace"
        ],
        "type": "string"
      },
      "maxItems": 6,
      "type": "array"
    },
    "site_id": {
      "description": "The row: a non-production site or environment.",
      "minimum": 1,
      "type": "integer"
    },
    "start_with_request": {
      "description": "trigger (the default) or yes.",
      "enum": [
        "trigger",
        "yes"
      ],
      "type": "string"
    },
    "version": {
      "description": "corestack_php_runtime_get's `version`: a change made since is refused `stale`.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "enabled",
    "version"
  ],
  "type": "object"
}
```

## Refusals

- `invalid_arguments`: Xdebug is for non-production rows only (`details.errors` lists {field, code, message}; the entry for `enabled` carries `non_production_only`), or `mode` is empty or names a mode twice.
- `stale`: the row's PHP configuration changed since you read it; read corestack_php_runtime_get again and call with its new `version`.
- `runtime_locked`: Corefinity has locked this row's PHP configuration, so nothing was changed; tell the person (Corefinity support can unlock it).
- `managed_elsewhere`: another control panel manages this row; change it there.
- `switched_off`: the `exec` kill switch is off, which also stops every PHP change on a row already on the new runtime; stop and tell the person.
- `feature_off`: `apply: "tonight"` needs the maintenance window queue, which is switched off; leave `apply` out to make the change now.
- `batch_window`: this change can only apply inside this row's maintenance window, or other maintenance is already queued for it; call again with `apply: "tonight"`.
- `change_pending`: a change is already queued for this row's maintenance window; apply or cancel it first (corestack_pending_changes_list).
- `runtime_not_adopted`: the row is not on the new runtime yet and cannot move onto it with this save (`details.adoption` says why); try again once corestack_runtime_get shows it can adopt.
- `conflict`: the row's PHP files were changed outside the Control Panel, and Corefinity staff review them before the next change; nothing was changed; tell the person.
- `removed`: the row has been removed.
- `deleted`: the site is deleted (in its grace period); restore it with corestack_site_restore_deleted first.
- `provisioning`: the site is still being created; wait for corestack_site_provisioning_get to finish.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_php_xdebug_set",
  "arguments": {
    "site_id": 4212,
    "enabled": true,
    "mode": [
      "debug"
    ],
    "start_with_request": "trigger",
    "idekey": "PHPSTORM",
    "version": 3
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_php_xdebug_set with site_id 4212, enabled true, mode ["debug"], start_with_request trigger, idekey PHPSTORM, version 3. (Set up Xdebug.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [PUT /api/corestack/sites/{site}/php-runtime](https://docs.corefinity.com/api/reference/runtime/update-php-runtime.md)
- Guide: [PHP configuration](https://docs.corefinity.com/guides/sites/software-and-services/php-settings-and-php-ini.md)
