Compatibilidad Xdebug y SPX

Technical reference synchronized with Yard’s source. File names and development commands refer to the native app repository.

Yard installs verified modules for its own PHP builds. It does not run a Herd installer, compile on the user's Mac, invoke Homebrew, replace PHP or restart unrelated services. Open Settings → Mail & Debugging → Debugger, or use:

yard php:extensions --php 8.4
yard php:extension:install xdebug --php 8.4
yard php:extension:install spx --php 8.4

Installation is explicit and runs off the UI thread. Restart only the selected PHP version with the button offered after installation; existing FPM workers keep their parsed configuration until restarted. Installation progress and pending restarts belong to the app and survive navigating away from Debugger. Another install is disabled while an operation is running. The restart notice remains after a failed restart and clears once both replacement FPM pools are ready, including after a general service restart. yard debug, yard coverage and yard profile diagnose an inactive extension before starting the command. Existing manually configured compatible modules remain usable; the installer refuses to overwrite a custom loader. Remove that loader explicitly before opting into a managed installation.

Compatibility evidence

Xdebug and SPX are available for every PHP minor currently downloadable in Yard: 8.0–8.5. All builds below are Apple Silicon, NTS and non-debug. PHP 7.4 and 8.6 remain inventory entries without published CLI/FPM downloads; they are not advertised as installable extension targets.

Each row passed real CLI/FPM breakpoints, full and live CLI profiles, a web profile, call-breakdown data, access-control checks and ordinary requests with profiling inactive. Installation inspects both real executables, compares their APIs, checks the artifact's minor/API and loads the module in each before activation. Later patches must pass these runtime checks; this table records the exact builds tested.

Existing PHP 8.0 installations

The provider's original 8.0.30 executables omit PHP's dynamic extension exports. Update PHP 8.0 through Yard or run yard php:update 8.0 before installing its modules. Yard's bundled 8.0.30-yard1 build preserves all original extensions and exports the required API in CLI and FPM. It appears as an update over the same upstream patch. Updating PHP is explicit; installing a module does not silently replace a runtime. The replacement verifies both binaries first and preserves the previous pair on a failed installation.

The runtime and modules were checked for arm64, macOS deployment targets no higher than 14.0, valid ad-hoc signatures and links only to macOS system libraries. HTTPS was also checked in the rebuilt 8.0 runtime. Tests ran on the current Apple Silicon host, not on a physical macOS 14 machine.

Artifacts and build-machine preparation

The user never compiles PHP or installs Homebrew. Maintainers prepare PHP 8.0's repaired runtime with scripts/vendor/php80-runtime.py, using the pinned Static PHP CLI source, original Protobuf/Swoole versions and PHP SDK sources in scripts/vendor/sources.lock.json. The recipe handles the legacy compiler, libxml, ICU and PostgreSQL compatibility adjustments and preserves source/license provenance. It requires existing Xcode tools, Autoconf/Autoheader, Automake, re2c, bison, CMake, a PHP 8.3+ bootstrap and Composer:

python3 scripts/vendor/php80-runtime.py --bootstrap-php /path/to/php85 --composer /path/to/composer.phar

To stage an existing compiled workspace after verifying both executables:

python3 scripts/vendor/php80-runtime.py --stage-from /path/to/pinned-spc-workspace

Provide each offered runtime as <minor>/php and <minor>/php-fpm, using the repaired pair for 8.0:

bash scripts/vendor/php-extensions.sh --all /path/to/runtimes --work /path/without/spaces/extension-build

A single pair can also be prepared with php-extensions.sh /path/to/php /path/to/php-fpm. The builder uses the matching pinned PHP SDK for each minor, compiles Xdebug, and stages the independently checksummed SPX provider archive selected by its php-<minor> role in the V1 download catalog. It verifies both modules in the actual CLI/FPM before publishing the payload. No compiler is invoked by the app.

Outputs are vendor-build/out/php-extensions/{xdebug,spx}/<minor>/ and vendor-build/out/php-runtimes/8.0/. Xdebug retains its license and PHP's license; SPX retains its GPL license, web assets and matching upstream source archive. Runtime payloads include third-party notices and a source/input checksum receipt. Do not commit these build outputs.

build-app.sh checks all twelve module payloads, their notices and checksums, the repaired 8.0 runtime and its deployment target before including them. Missing modules for a downloadable PHP minor block packaging. Source hashes are pinned in scripts/vendor/sources.lock.json; SPX archive hashes are in the V1 catalog and scripts/vendor/upstream-downloads.json. The public download generator keeps each PHP-specific role when multiple Xdebug artifacts share a version.

Configuration, privacy and recovery

Modules live under YARD_HOME/php-extensions/<extension>/<minor>/. Xdebug adds a marked block to that minor's config/php/<minor-without-dot>/debug.ini; the normal ini never loads it. Its debug block disables JIT only for debug pools. SPX adds a marked block to the normal ini, with profiling inactive unless requested, loopback IP restriction, Yard-owned web assets and private YARD_HOME/profiler/ report storage. CLI profiling is explicit:

yard profile artisan inspire
yard profile --live artisan inspire

Both commands emit a flat profile; --live enables SPX's live flat-profile refresh. The web dashboard records full reports and opens the upstream call breakdown with authenticated same-origin cookies. Saving browser profiling preferences requires its form token. A private random profiler key uses Yard's Keychain mechanism; the required ini copy is owner-readable only. Keys and phpinfo output are never logged. The dashboard contains request URLs and command lines supplied by profiled applications; treat those reports as private development data.

Replacement stages and verifies the full artifact before publication, then checks the final ini in CLI and FPM without connecting to an IDE. A failed load restores the prior module directory and exact prior ini bytes. A per-extension cross-process lock prevents simultaneous replacements. User ini settings outside the marked block survive, and repeat installation produces one loader. Corrupt downloads and unsupported ABI builds cannot change the current installation. Interrupted manual recovery can restore a .previous-* directory under the extension's parent; inspect it and the ini before starting affected FPM workers. Do not delete a prior payload until deciding which copy to retain.

To clean profiles, first turn off profiling in the dashboard and stop an active CLI profile, then remove only the desired files from YARD_HOME/profiler/. No automatic pruning or project database cleanup is performed.

Repeatable validation

python3 Tests/php-extension-build-tests.py
python3 Tests/vendor-release-tests.py
python3 scripts/vendor/verify-php-extensions.py vendor-build/out/php-extensions --require-all

YARD_PHP_EXTENSION_INTEGRATION=1 \
YARD_PHP_EXTENSION_MATRIX=/path/to/runtimes \
YARD_PHP_EXTENSION_PAYLOAD_ROOT=/path/to/vendor-build/out/php-extensions \
YARD_PHP_EXTENSION_ARCHIVE_ROOT=/path/to/extension-build/spx-archives \
swift test --filter 'PHPExtensionTests|BundledPHPRuntimeTests|PHPVersionManagerTests'

For the 8.0 upgrade case, supply the original provider executables as 8.0-stock/php and 8.0-stock/php-fpm alongside the repaired 8.0/ pair. The fixture verifies the update is offered, installs the bundled runtime, then checks its debugger and profiler. YARD_PHP_EXTENSION_MINORS can select a comma-separated subset for development; omit it for the full catalog. The original four YARD_PHP_EXTENSION_CLI, YARD_PHP_EXTENSION_FPM, YARD_PHP_EXTENSION_XDEBUG_PAYLOAD and YARD_PHP_EXTENSION_SPX_ARCHIVE inputs still select a single 8.4 case.

On 2026-11-09 all 20 Swift tests passed without skips, including real integration for all six PHP minors. The five extension packaging/catalog tests and fifteen vendor release tests also passed. Fixtures use separate homes with spaces, fixture keys instead of Keychain, and only their own FPM processes on allocated loopback ports. No habitual app, resolver, certificate trust, Keychain record or service is changed. The IDE breakpoint watcher and nginx routing retain their implementation; integration checks the actual FPM protocol.