# Migrate to Debug 0.2

> For applications upgrading from 0.1, start with the upgrade checklist.

For applications upgrading from 0.1, start with the [upgrade checklist](https://github.com/yii2-extensions/debug/blob/main/UPGRADE.md). The 0.2 line targets Yii
22.0, including standalone module actions and immutable factories. It does not support Yii 2.0.x.

## Stored requests and assets

Old serialized 0.1 captures cannot be read by the versioned JSON store in 0.2. Stop development traffic before
cleaning the configured `dataPath`. To preserve history for rollback, first back up the 0.1 `.data` captures and
their `index.data` manifest. Remove only old debugger data; do not clear unrelated runtime state. Treat stored
captures as sensitive.

Shared contracts live in `php-forge/debug`; shared storage, presentation, views and the compiled frontend live in
`php-forge/debug-core`. Yii's `DebugAsset` and `ToolbarAsset` publish those packaged assets. Remove direct
references to the old `DbAsset`, `PhpInfoAsset`, `TimelineAsset` and `UserswitchAsset` classes. Custom markup uses
`data-yii-debug-toggle`; the old `data-toggle` alias is gone. No consumer-side Node.js build is needed.

## Collectors, panels and providers

Custom collectors and panels must match the current contracts rather than importing removed internal helper
classes. A collector implements `PHPForge\Debug\CollectorInterface`; a portable panel uses
`PHPForge\Debug\Panel`. For Yii-owned panels, consult `yii\debug\Panel` at the installed revision and adapt
capture/hydration to typed snapshots. `QueryRow` exposes getters instead of its former public properties.

Optional Vite and Inertia integrations now belong to their provider packages. Register the collector and panel
explicitly under their shared stable ID, then use `dispatchers` for an existing component that accepts the
collector. The module does not autodetect provider packages. Use the capture-policy closure for Inertia to redact
props and URLs. See the [current configuration](/docs/extensions/debug/configuration/index.md#provider-packages).

The standalone Timeline panel/collector was removed; use Profiling and its timeline. Router appears inside
Request by default and can be enabled as a separate panel. Mail and Queue are built-ins; `position` is rejected
for built-in panels. Extensions are ordered by configured position, then title, and include enabled panels with
no activity. Disable both a provider's collector and panel before removing its package.

## Actions and custom integrations

The module dispatches standalone actions from `Module::$actionMap`. Code coupled to the former debug controller
must use the current action/module APIs and route generation. Keep identity-action access and HTTP method
checks when extending those actions. Module services can be replaced through `components` before resolution;
see [module services](/docs/extensions/debug/configuration/index.md#module-services).

`Module::VERSION` was removed; use `Module::getVersion()`. `DebugSearch::$criticalCodes` was removed: every `4xx`
and `5xx` capture is now critical, and History provides a Status column. Internal search matchers, row
normalizers and former shell DTOs are not supported extension points. Check PHPDoc at the installed revision
when migrating code that used them.

Verify application requests, stored capture loading, denied access, custom actions, provider events and asset
loading after the upgrade. Keep the original application lockfile available for rollback. Returning to 0.1 can
read retained or restored 0.1 `.data` captures with their matching manifest; it cannot read new JSON captures
written by 0.2.