Documentation

XdebugHandler
in package

Tags
author

John Stevenson john-stevenson@blueyonder.co.uk

Table of Contents

DEBUG  = 'XDEBUG_HANDLER_DEBUG'
RESTART_ID  = 'internal'
RESTART_SETTINGS  = 'XDEBUG_HANDLER_SETTINGS'
SUFFIX_ALLOW  = '_ALLOW_XDEBUG'
SUFFIX_INIS  = '_ORIGINAL_INIS'
$tmpIni  : string|null
$cli  : mixed
$debug  : mixed
$envAllowXdebug  : mixed
$envOriginalInis  : mixed
$inRestart  : mixed
$loaded  : mixed
$mode  : mixed
$name  : mixed
$persistent  : mixed
$script  : mixed
$skipped  : mixed
$statusWriter  : Status|null
$xdebugActive  : mixed
__construct()  : mixed
Constructor
check()  : mixed
Checks if Xdebug is loaded and the process needs to be restarted
getAllIniFiles()  : array<string|int, mixed>
Returns an array of php.ini locations with at least one entry
getRestartSettings()  : array<string|int, mixed>|null
Returns an array of restart settings or null
getSkippedVersion()  : string
Returns the Xdebug version that triggered a successful restart
isXdebugActive()  : bool
Returns whether Xdebug is loaded and active
setLogger()  : $this
Activates status message output to a PSR3 logger
setMainScript()  : $this
Sets the main script location if it cannot be called from argv
setPersistent()  : $this
Persist the settings to keep Xdebug out of sub-processes
requiresRestart()  : bool
Allows an extending class to decide if there should be a restart
restart()  : mixed
Allows an extending class to access the tmpIni
checkConfiguration()  : bool
Returns true if there are no known configuration issues
checkMainScript()  : bool
Returns true if the script name can be used
checkScanDirConfig()  : bool
Returns true if there are scanned inis and PHP is able to report them
doRestart()  : mixed
Executes the restarted command then deletes the tmp ini
getCommand()  : array<string|int, mixed>
Returns the command line arguments for the restart
mergeLoadedConfig()  : string
Returns default, changed and command-line ini settings
notify()  : mixed
Logs status messages
prepareRestart()  : bool
Returns true if everything was written for the restart
setEnvironment()  : bool
Returns true if the restart environment variables were set
setEnvRestartSettings()  : mixed
Adds restart settings to the environment
syncSettings()  : mixed
Syncs settings and the environment if called with existing settings
tryEnableSignals()  : mixed
Enables async signals and control interrupts in the restarted process
writeTmpIni()  : bool
Returns true if the tmp ini file was written

Constants

RESTART_SETTINGS

public mixed RESTART_SETTINGS = 'XDEBUG_HANDLER_SETTINGS'

Properties

Methods

__construct()

Constructor

public __construct(string $envPrefix) : mixed

The $envPrefix is used to create distinct environment variables. It is uppercased and prepended to the default base values. For example 'myapp' would result in MYAPP_ALLOW_XDEBUG and MYAPP_ORIGINAL_INIS.

Parameters
$envPrefix : string

Value used in environment variables

Tags
throws
RuntimeException

If the parameter is invalid

Return values
mixed

check()

Checks if Xdebug is loaded and the process needs to be restarted

public check() : mixed

This behaviour can be disabled by setting the MYAPP_ALLOW_XDEBUG environment variable to 1. This variable is used internally so that the restarted process is created only once.

Return values
mixed

getAllIniFiles()

Returns an array of php.ini locations with at least one entry

public static getAllIniFiles() : array<string|int, mixed>

The equivalent of calling php_ini_loaded_file then php_ini_scanned_files. The loaded ini location is the first entry and may be empty.

Return values
array<string|int, mixed>

getRestartSettings()

Returns an array of restart settings or null

public static getRestartSettings() : array<string|int, mixed>|null

Settings will be available if the current process was restarted, or called with the settings from an existing restart.

Return values
array<string|int, mixed>|null

getSkippedVersion()

Returns the Xdebug version that triggered a successful restart

public static getSkippedVersion() : string
Return values
string

isXdebugActive()

Returns whether Xdebug is loaded and active

public static isXdebugActive() : bool

true: if Xdebug is loaded and is running in an active mode. false: if Xdebug is not loaded, or it is running with xdebug.mode=off.

Return values
bool

setMainScript()

Sets the main script location if it cannot be called from argv

public setMainScript(string $script) : $this
Parameters
$script : string
Return values
$this

setPersistent()

Persist the settings to keep Xdebug out of sub-processes

public setPersistent() : $this
Return values
$this

requiresRestart()

Allows an extending class to decide if there should be a restart

protected requiresRestart(bool $default) : bool

The default is to restart if Xdebug is loaded and its mode is not "off". Do not typehint for 1.x compatibility.

Parameters
$default : bool

The default behaviour

Return values
bool

Whether the process should restart

restart()

Allows an extending class to access the tmpIni

protected restart(array<string|int, mixed> $command) : mixed

Do not typehint for 1.x compatibility

Parameters
$command : array<string|int, mixed>
Return values
mixed

checkConfiguration()

Returns true if there are no known configuration issues

private checkConfiguration(string &$info) : bool
Parameters
$info : string

Set by method

Return values
bool

checkMainScript()

Returns true if the script name can be used

private checkMainScript() : bool
Return values
bool

checkScanDirConfig()

Returns true if there are scanned inis and PHP is able to report them

private checkScanDirConfig() : bool

php_ini_scanned_files will fail when PHP_CONFIG_FILE_SCAN_DIR is empty. Fixed in 7.1.13 and 7.2.1

Return values
bool

doRestart()

Executes the restarted command then deletes the tmp ini

private doRestart(array<string|int, mixed> $command) : mixed
Parameters
$command : array<string|int, mixed>
Return values
mixed

getCommand()

Returns the command line arguments for the restart

private getCommand() : array<string|int, mixed>
Return values
array<string|int, mixed>

mergeLoadedConfig()

Returns default, changed and command-line ini settings

private mergeLoadedConfig(array<string|int, mixed> $loadedConfig, array<string|int, mixed> $iniConfig) : string
Parameters
$loadedConfig : array<string|int, mixed>

All current ini settings

$iniConfig : array<string|int, mixed>

Settings from user ini files

Return values
string

notify()

Logs status messages

private notify(string $op[, null|string $data = null ]) : mixed
Parameters
$op : string

Status handler constant

$data : null|string = null

Optional data

Return values
mixed

prepareRestart()

Returns true if everything was written for the restart

private prepareRestart() : bool

If any of the following fails (however unlikely) we must return false to stop potential recursion:

  • tmp ini file creation
  • environment variable creation
Return values
bool

setEnvironment()

Returns true if the restart environment variables were set

private setEnvironment(bool $scannedInis, array<string|int, mixed> $iniFiles) : bool

No need to update $_SERVER since this is set in the restarted process.

Parameters
$scannedInis : bool

Whether there were scanned ini files

$iniFiles : array<string|int, mixed>

All ini files used in the current process

Return values
bool

setEnvRestartSettings()

Adds restart settings to the environment

private setEnvRestartSettings(array<string|int, string> $envArgs) : mixed
Parameters
$envArgs : array<string|int, string>
Return values
mixed

syncSettings()

Syncs settings and the environment if called with existing settings

private syncSettings(array<string|int, mixed> $settings) : mixed
Parameters
$settings : array<string|int, mixed>
Return values
mixed

tryEnableSignals()

Enables async signals and control interrupts in the restarted process

private tryEnableSignals() : mixed

Available on Unix PHP 7.1+ with the pcntl extension and Windows PHP 7.4+.

Return values
mixed

writeTmpIni()

Returns true if the tmp ini file was written

private writeTmpIni(array<string|int, mixed> $iniFiles, string $tmpDir, string &$error) : bool
Parameters
$iniFiles : array<string|int, mixed>

All ini files used in the current process

$tmpDir : string

The system temporary directory

$error : string

Set by method if ini file cannot be read

Return values
bool

Search results