xdebug handler
3.0.5
Redémarrez un processus CLI sans charger l'extension Xdebug, sauf si xdebug.mode=off .
Initialement écrit dans le cadre de composer/composer, maintenant extrait et mis à disposition sous forme de bibliothèque autonome.
Suppression de la prise en charge des anciennes versions de PHP et ajout des déclarations de type.
La prise en charge à long terme de la version 2 (PHP 5.3.2 - 7.2.4) suit la politique de Composer 2.2 LTS.
Installez la dernière version avec :
$ composer require composer/xdebug-handler use Composer XdebugHandler XdebugHandler ;
$ xdebug = new XdebugHandler ( ' myapp ' );
$ xdebug -> check ();
unset( $ xdebug ); Le constructeur prend un seul paramètre, $envPrefix , qui est en majuscule et ajouté aux valeurs de base par défaut pour créer deux variables d'environnement distinctes. L'exemple ci-dessus permet d'utiliser :
MYAPP_ALLOW_XDEBUG=1 pour remplacer le redémarrage automatique et autoriser XdebugMYAPP_ORIGINAL_INIS pour obtenir les emplacements des fichiers ini dans un processus redémarré Un fichier ini temporaire est créé à partir des fichiers ini chargés (et analysés), avec toutes les références à l'extension Xdebug commentées. Les paramètres ini actuels sont fusionnés, de sorte que la plupart des paramètres ini définis sur la ligne de commande ou par l'application soient inclus (voir Limitations).
MYAPP_ALLOW_XDEBUG est défini avec des données internes à signaler et à utiliser lors du redémarrage.MYAPP_ALLOW_XDEBUG n'est pas défini.Voir Exemples pour plus d'informations.
La gestion du signal asynchrone est automatiquement activée si l'extension pcntl est chargée. SIGINT est défini sur SIG_IGN dans le processus parent et restauré sur SIG_DFL dans le processus redémarré (si aucun autre gestionnaire n'a été défini).
Depuis PHP 7.4 sous Windows, la gestion CTRL+C et CTRL+BREAK est automatiquement activée dans le processus redémarré et ignorée dans le processus parent.
Il y a quelques points à prendre en compte lors de l'exécution dans un processus redémarré.
Ces méthodes statiques fournissent des informations sur le processus en cours, qu'il ait été redémarré ou non.
Renvoie un tableau des emplacements des fichiers ini d'origine. Utilisez-le au lieu d'appeler php_ini_loaded_file et php_ini_scanned_files , qui signaleront les valeurs incorrectes lors d'un processus redémarré.
use Composer XdebugHandler XdebugHandler ;
$ files = XdebugHandler:: getAllIniFiles ();
# $ files [ 0 ] always exists , it could be an empty string
$ loadedIni = array_shift ( $ files );
$ scannedInis = $ files ; Ces emplacements sont également disponibles dans la variable d'environnement MYAPP_ORIGINAL_INIS . Il s'agit d'une chaîne séparée par des chemins comprenant l'emplacement renvoyé par php_ini_loaded_file , qui peut être vide, suivi des emplacements analysés lors de l'appel php_ini_scanned_files .
Renvoie un tableau de paramètres pouvant être utilisés avec les sous-processus PHP, ou null si le processus n'a pas été redémarré.
use Composer XdebugHandler XdebugHandler ;
$ settings = XdebugHandler:: getRestartSettings ();
/**
* $ settings : array ( if the current process was restarted ,
* or called with the settings from a previous restart ) , or null
*
* ' tmp Ini ' = > the temporary ini file used in the restart ( string )
* ' scanned Inis ' = > if there were any scanned inis ( bool )
* ' scan Dir ' = > the original PHP _ INI _ SCAN _ DIR value ( false |string )
* ' phprc ' = > the original PHPRC value ( false |string )
* ' inis ' = > the original inis from get AllIniFiles ( array )
* ' skipped ' = > the skipped version from get SkippedVersion ( string )
*/ Renvoie la chaîne de version de Xdebug qui a été ignorée par le redémarrage, ou une chaîne vide s'il n'y a pas eu de redémarrage (ou si Xdebug est toujours chargé, peut-être par le redémarrage d'une classe d'extension pour une raison autre que la suppression de Xdebug).
use Composer XdebugHandler XdebugHandler ;
$ version = XdebugHandler:: getSkippedVersion ();
# $version : ' 3.1 . 1 ' ( for example ) , or an empty string Renvoie vrai si Xdebug est chargé et s'exécute en mode actif (s'il prend en charge les modes). Renvoie false si Xdebug n'est pas chargé ou s'il s'exécute avec xdebug.mode=off .
Ces méthodes implémentent une interface fluide et doivent être appelées avant la méthode principale check() .
Permet la sortie de messages d'état vers un enregistreur PSR3 externe. Tous les messages sont signalés avec des niveaux de journalisation DEBUG ou WARNING . Par exemple (affichant le niveau et le message) :
// No restart
DEBUG Checking MYAPP_ALLOW_XDEBUG
DEBUG The Xdebug extension is loaded (3.1.1) xdebug.mode=off
DEBUG No restart (APP_ALLOW_XDEBUG=0) Allowed by xdebug.mode
// Restart overridden
DEBUG Checking MYAPP_ALLOW_XDEBUG
DEBUG The Xdebug extension is loaded (3.1.1) xdebug.mode=coverage,debug,develop
DEBUG No restart (MYAPP_ALLOW_XDEBUG=1)
// Failed restart
DEBUG Checking MYAPP_ALLOW_XDEBUG
DEBUG The Xdebug extension is loaded (3.1.0)
WARNING No restart (Unable to create temp ini file at: ...)
Les messages d'état peuvent également être générés avec XDEBUG_HANDLER_DEBUG . Voir Dépannage.
Définit l'emplacement du script principal à exécuter au redémarrage. Ceci n'est nécessaire que dans des cas d'utilisation plus ésotériques ou si l'emplacement argv[0] est inaccessible. Le nom du script -- est pris en charge pour l'entrée standard.
Configure le redémarrage à l'aide de paramètres persistants, afin que Xdebug ne soit chargé dans aucun sous-processus.
Utilisez cette méthode si votre application appelle un ou plusieurs sous-processus PHP et que l'extension Xdebug n'est pas nécessaire. Cela évite les frais généraux liés à la mise en œuvre de stratégies de sous-processus spécifiques.
Alternativement, cette méthode peut être utilisée pour configurer un environnement par défaut sans Xdebug qui peut être modifié si un sous-processus nécessite Xdebug, puis restauré par la suite :
function SubProcessWithXdebug ()
{
$ phpConfig = new Composer XdebugHandler PhpConfig ();
# Set the environment to the original configuration
$ phpConfig -> useOriginal ();
# run the process with Xdebug loaded
. . .
# Restore Xdebug - free environment
$ phpConfig -> usePersistent ();
}La bibliothèque propose deux stratégies pour appeler un nouveau processus PHP sans charger Xdebug, en utilisant des paramètres standard ou persistants . Notez que ceci n'est important que si l'application appelle un sous-processus PHP.
Utilise les options de ligne de commande pour supprimer Xdebug du nouveau processus uniquement.
Si le nouveau processus appelle un sous-processus PHP, Xdebug sera chargé dans ce sous-processus (sauf s'il implémente xdebug-handler, auquel cas il y aura un autre redémarrage).
Il s'agit de la stratégie par défaut utilisée lors du redémarrage.
Utilise des variables d'environnement pour supprimer Xdebug du nouveau processus et conserver ces paramètres dans n'importe quel sous-processus.
PHP_INI_SCAN_DIR est défini sur une chaîne vide. Cela indique à PHP de ne pas rechercher des inis supplémentaires.PHPRC est défini sur l'ini temporaire.Si le nouveau processus appelle un sous-processus PHP, Xdebug ne sera pas chargé dans ce sous-processus.
Cette stratégie peut être utilisée lors du redémarrage en appelant setPersistent().
La classe d'assistance PhpConfig facilite l'invocation d'un sous-processus PHP (avec ou sans Xdebug chargé), qu'il y ait eu ou non un redémarrage.
Chacune de ses méthodes renvoie un tableau d'options PHP (à ajouter à la ligne de commande) et configure l'environnement pour la stratégie requise. La méthode getRestartSettings() est utilisée en interne.
useOriginal() - Xdebug sera chargé dans le nouveau processus.useStandard() - Xdebug ne sera pas chargé dans le nouveau processus - voir les paramètres standard.userPersistent() - Xdebug ne sera pas chargé dans le nouveau processus - voir les paramètres persistantsS'il n'y a pas eu de redémarrage, un tableau d'options vide est renvoyé et l'environnement n'est pas modifié.
use Composer XdebugHandler PhpConfig ;
$ config = new PhpConfig ;
$ options = $ config -> useOriginal ();
# $options : empty array
# environment : PHPRC and PHP _ INI _ SCAN _ DIR set to original values
$ options = $ config -> useStandard ();
# $options : [ - n , - c , tmp Ini ]
# environment : PHPRC and PHP _ INI _ SCAN _ DIR set to original values
$ options = $ config -> usePersistent ();
# $options : empty array
# environment : PHPRC = tmpIni , PHP_INI_SCAN_DIR = ''Les paramètres d'environnement suivants peuvent être utilisés pour résoudre un comportement inattendu :
XDEBUG_HANDLER_DEBUG=1 Envoie des messages d'état à STDERR , s'il est défini, quel que soit l'enregistreur PSR3. Chaque message porte le préfixe xdebug-handler[pid] , où pid est l'identifiant du processus.
XDEBUG_HANDLER_DEBUG=2 Comme ci-dessus, mais enregistre en plus le fichier ini temporaire et signale son emplacement dans un message d'état.
L'API est définie par des classes et leurs éléments accessibles qui ne sont pas annotés comme @internal. La classe principale possède deux méthodes protégées qui peuvent être remplacées pour fournir des fonctionnalités supplémentaires :
Par défaut, le processus redémarrera si Xdebug est chargé et ne fonctionne pas avec xdebug.mode=off . L'extension de cette méthode permet à une application de décider, en renvoyant une valeur booléenne (ou équivalente). Elle n'est appelée que si MYAPP_ALLOW_XDEBUG est vide, elle ne sera donc pas appelée dans le processus redémarré (où cette variable contient des données internes), ou si le redémarrage a été remplacé.
Notez que les setters setMainScript() et setPersistent() peuvent être utilisés ici, si nécessaire.
Une application peut étendre cela pour modifier le fichier ini temporaire, son emplacement étant indiqué dans la propriété tmpIni . Les nouveaux paramètres peuvent être ajoutés en toute sécurité à la fin des données, qui se terminent par PHP_EOL .
Le paramètre $command est un tableau d'arguments de ligne de commande non échappés qui seront utilisés pour le nouveau processus.
N'oubliez pas de terminer avec parent::restart($command) .
Cet exemple montre deux manières d'étendre les fonctionnalités de base :
Pour éviter la surcharge liée au lancement d'un nouveau processus, le redémarrage est ignoré si une simple commande d'aide est demandée.
L'application a besoin d'un accès en écriture aux fichiers phar, elle forcera donc un redémarrage si phar.readonly est défini (que Xdebug soit chargé ou non) et modifiera cette valeur dans le fichier ini temporaire.
use Composer XdebugHandler XdebugHandler ;
use MyApp Command ;
class MyRestarter extends XdebugHandler
{
private $ required ;
protected function requiresRestart ( bool $ default ): bool
{
if (Command:: isHelp ()) {
# No need to disable Xdebug for this
return false ;
}
$ this -> required = ( bool ) ini_get ( ' phar.readonly ' );
return $ this -> required || $ default ;
}
protected function restart ( array $ command ): void
{
if ( $ this -> required ) {
# Add required ini setting to tmp Ini
$ content = file_get_contents ( $ this -> tmpIni );
$ content .= ' phar.readonly=0 ' . PHP_EOL ;
file_put_contents ( $ this -> tmpIni , $ content );
}
parent :: restart ( $ command );
}
} Le répertoire testsApp contient des scripts de ligne de commande qui démontrent le fonctionnement interne dans divers scénarios. Voir Scripts de tests fonctionnels.
composer/xdebug-handler est sous licence MIT, voir le fichier LICENSE pour plus de détails.
