View source for Manual:How to debug/fr

<languages/>
{{TOC|align|right}}
Cette page donne une introduction de base au  '''débogage du logiciel MediaWiki'''.

Une des premières choses que vous remarquerez est que ''echo'' ne fonctionne généralement pas ; Cela fait partie de la conception générale.

Il existe plusieurs options de configuration pour faciliter le débogage. Celles qui suivent sont toutes <code>false</code> par défaut.
Activez-les en les mettant à <code>true</code> dans votre {{ll|Manual:LocalSettings.php|LocalSettings.php}} :

* {{wg|ShowExceptionDetails}} Activer plus de détails (comme une trace de la pile) à afficher sur la page ''Erreur fatale''.
* {{wg|DebugToolbar}} Affiche une barre d'outils sur la page avec le profilage, les messages de journal et plus encore.
* {{wg|ShowDebug}} Ajoute la partie ''log messages'' de wgDebugToolbar comme une liste brute à la page.
* {{wg|DevelopmentWarnings}} MediaWiki lancera des avis pour certaines conditions possibles d'erreur et pour les fonctions obsolètes.

Exemple de ligne à ajouter dans votre {{ll|Manual:LocalSettings.php|LocalSettings.php}} :

<syntaxhighlight lang="php">
$wgShowExceptionDetails = true;
</syntaxhighlight>

<span id="PHP_errors"></span>
== Erreurs PHP ==

Pour voir les erreurs PHP, ajoutez ceci à la seconde ligne du haut (juste sous le {{phpi|<?php}}) de {{ll|Manual:LocalSettings.php|LocalSettings.php}} :

<syntaxhighlight lang="php">
error_reporting( -1 );
ini_set( 'display_errors', 1 );
</syntaxhighlight>

Ou mettez-la dans {{ll|Manual:php.ini|php.ini}} :

<syntaxhighlight lang="ini">
error_reporting = E_ALL
display_errors = On
</syntaxhighlight>

Ou déclarez dans .htaccess :

<syntaxhighlight lang="apache">
php_value error_reporting -1
php_flag display_errors On
</syntaxhighlight>

Cela entraînera l'affichage des erreurs PHP sur la page. Cela pourrait aider les attaquants pour trouver un chemin dans votre serveur, alors désactivez-la à nouveau lorsque vous avez trouvé le problème.

Notez que des erreurs PHP ''fatales'' peuvent se produire avant que les lignes ci-dessus ne se soient exécutées, ou peuvent empêcher leur affichage.
Les erreurs fatales de PHP sont généralement enregistrées dans le journal des erreurs d'Apache - vérifiez le paramètre <code>[https://php.net/error_log error_log]</code> dans <code>php.ini</code> (ou utilisez <code>[https://php.net/phpinfo phpinfo()]</code>)

<span id="Turning_display_startup_errors_on"></span>
=== Activation de l'affichage des erreurs au démarrage (display_startup_errors) ===
Certains fournisseurs désactivent <code>display_startup_errors</code>, ce qui masque les erreurs même si vous relancez le niveau <code>error_reporting</code>.
Activer le programme est trop tard ! Au lieu de cela, vous devrez créer un fichier wrapper autour de votre fichier.
Dans le cas de MediaWiki vous pouvez simplement ajouter ceci au-dessus de mediawiki/index.php :

<syntaxhighlight lang="php">
--- index.php
    error_reporting( -1 );
    ini_set( 'display_startup_errors', 1 );
    ini_set( 'display_errors', 1 );
</syntaxhighlight>

Dans d'autres environnements :

<syntaxhighlight lang="php">
--- myTestFile.php
    error_reporting( -1 );
    ini_set( 'display_startup_errors', 1 );
    ini_set( 'display_errors', 1 );
    require 'your_file.php';
</syntaxhighlight>

<span id="SQL_errors"></span>
== Erreurs SQL ==

Pour tracer toutes les requêtes SQL plutôt que uniquement celle qui a levé l'exception, fixez la valeur de $l dans <code>LocalSettings.php</code> :

<syntaxhighlight lang="php">
$wgDebugDumpSql = true;
</syntaxhighlight>

{{MW version|version=1.16|version2=1.31}}
Avant MediaWiki 1.32, vous deviez initialiser {{manual|$wgShowSQLErrors}} et {{manual|$wgShowDBErrorBacktrace}} pour voir les exceptions détaillées de la base de données dans la sortie HTML :

<syntaxhighlight lang="php">
$wgShowSQLErrors = true;
$wgShowDBErrorBacktrace = true;
</syntaxhighlight>

<span id="In-depth_debugging"></span>
== Débogage en profondeur ==

<span id="Debugger"></span>
=== Débogueur ===

Vous pouvez déboguer votre code étape par étape avec {{ll|XDebug}}. Pour certaines configurations courantes, voir :

* [[MediaWiki-Docker/Configuration recipes/Xdebug|MediaWiki-Docker]]
* [[Cli/guide/Docker-Development-Environment/MediaWiki#XDebug|mwcli]]
* [[Manual:How to debug/with MediaWiki-Vagrant and PHPStorm|Vagrant with PHPStorm]]
* [[MediaWiki-Vagrant/Advanced_usage#MediaWiki_debugging_using_Xdebug_and_an_IDE_in_your_host|Vagrant with other IDEs]]
* [[Manual:Running_MediaWiki_on_macOS#Setting_up_XDebug_with_PhpStorm|MacOS]]

MediaWiki-Vagrant possède [https://phabricator.wikimedia.org/diffusion/MWVA/browse/master/puppet/modules/php/manifests/remote_debug.pp;c377718dea960c5e9e7b3acc79893a5e3c14da01$27 des paramètres intégrés] pour cela.
Si vous n'utilisez pas MediaWiki-Vagrant, mais que votre configuration est similaire, vous pouvez réutiliser ces valeurs.
Dans certains cas (comme par exemple la présence d'un pare-feu), vous devrez peut-être utiliser l'IDE sur la même machine que le serveur web.
Dans ce cas, définissez simplement :

<syntaxhighlight lang="ini">
xdebug.remote_enable = 1
xdebug.remote_host = 'localhost'
</syntaxhighlight>

Voir la [https://xdebug.org/docs/remote documentation XDebug] pour plus d'informations.

Pour déboguer un script de ligne de commande (par exemple PHPUnit ou un script de maintenance) sur MediaWiki-Vagrant, utilisez :

<syntaxhighlight lang="php">
xdebug_on; php /vagrant/mediawiki/path/to/script.php --wiki=wiki ; xdebug_off
</syntaxhighlight>

Ajuster le script, les paramètres et l'hôte distant (ça devrait être l'adresse IP de l'ordinateur où se trouve votre IP, 10.0.2.2 devrait fonctionner pour [[MediaWiki-Vagrant]]) si nécessaire.

<span id="Logging"></span>
=== Journalisation ===

Pour plus de détails, vous devez faire un profil et consigner les erreurs. 

{{Note|1=Les instructions ci-dessous ne sont valables que pour la configuration par défaut. Si vous modifiez <code>{{ll|Manual:$wgMWLoggerDefaultSpi|$wgMWLoggerDefaultSpi}}</code> par exemple pour activer le rôle <code>psr3</code> sur une case {{ll|MediaWiki-Vagrant|vagrant}}, ces paramètres seront probablement ignorés. Voir dans ce case la documentation de votre traceur, comme {{ll|Manual:MonologSpi}}.}}

<span id="Setting_up_a_debug_log_file"></span>
==== Configuration d'un fichier journal de débogage ====

Pour enregistrer les erreurs et les informations de débogage dans un journal, ajoutez <code>{{ll|Manual:$wgDebugLogFile|$wgDebugLogFile}}</code> au fichier <code>LocalSettings.php</code>. Modifiez la valeur vers un fichier texte où vous souhaitez enregistrer la sortie des traces de débogage.

Le logiciel MediaWiki doit avoir les droits de votre système d'exploitation pour créer et écrire dans ce fichier, par exemple dans une installation par défaut Ubuntu, il s'exécute en tant qu'utilisateur et groupe <code>www-data</code>:<code>www-data</code> .
Voici un exemple de réglage :

<syntaxhighlight lang="php">
/**
 * The debug log file must never be publicly accessible because it contains private data.
 * But ensure that the directory is writeable by the PHP script running within your Web server.
 * The filename is with the database name of the wiki.
 */
$wgDebugLogFile = "/var/log/mediawiki/debug-{$wgDBname}.log";
</syntaxhighlight>

Ce fichier contiendra beaucoup d'informations de débogage à partir du noyau MediaWiki et des extensions.
Certains sous-systèmes écrivent dans des journaux personnalisés, voir [[#Creating a custom log file|#Création d'un fichier journal personnalisé]] pour capturer leur sortie.


{{warning|1=Le fichier journal de débogage peut contenir des informations privées telles que les informations de connexion, les cookies de session, et les valeurs des formulaires soumis. Si ces informations sont accessibles en public, les attaquants peuvent l'utiliser pour pirater et compromettre votre compte d'ordinateur et d'utilisateur. Si vous avez besoin de partager un journal de débogage à des fins de diagnostic, alors accédez au wiki sans y être connecté, et retirez du journal de débogage les lignes COOKIE, et n'exécutez aucune tentative de connexion.}}

<span id="Creating_a_custom_log_file"></span>
==== Création d'un fichier journal personnalisé ====
{{MW 1.31|and before}}
Avant Mediawiki 1.32, pour créer un fichier journal personnalisé qui ne contienne que vos instructions de débogage spécifiques, utilisez la fonction <code>wfErrorLog()</code>.
Cette fonction a deux paramètres: la chaîne de caractères à tracer et le chemin vers le fichier du journal :

<syntaxhighlight lang="php">
wfErrorLog( "An error occurred.\n", '/var/log/mediawiki/my-custom-debug.log' );
</syntaxhighlight>

<span id="Creating_custom_log_groups"></span>
==== Création de groupes de journaux personnalisés ====
Si vous effectuez le débogage de plusieurs composants différents, il peut être utile de diriger certains groupes de journaux à écrire dans un fichier distinct.
Voir {{ll|Manual:$wgDebugLogGroups|$wgDebugLogGroups}} pour plus d'informations.

Pour configurer des groupes de journaux personnalisés, utilisez les éléments suivants pour LocalSettings.php :

<syntaxhighlight lang="php">
/**
 * The debug log file should not be publicly accessible if it is used, as it
 * may contain private data. However, it must be in a directory to which PHP run
 * within your web server can write.
 *
 * Contrary to wgDebugLogFile, it is not necessary to include a wiki-id in these log file names
 * if you have multiple wikis. These log entries are prefixed with sufficient information to
 * identify the relevant wiki (web server hostname and wiki-id).
 */

// Groups from MediaWiki core
$wgDBerrorLog = '/var/log/mediawiki/dberror.log';
$wgDebugLogGroups = array(
	'exception' => '/var/log/mediawiki/exception.log',
	'resourceloader' => '/var/log/mediawiki/resourceloader.log',
	'ratelimit' => '/var/log/mediawiki/ratelimit.log',

	// Extra log groups from your extension
	#'myextension' => '/var/log/mediawiki/myextension.log',
	#'somegroup' => '/var/log/mediawiki/somegroup.log',
);
</syntaxhighlight>

Pour vous connecter à l'un de ces groupes, appelez <code>wfDebugLog</code> comme ceci :

<syntaxhighlight lang="php">
if ( $module->hasFailed ) {
    wfDebugLog( 'myextension', "Something is not right, module {$module->name} failed." );
}
</syntaxhighlight>

{{Tip|1=Si vous avez bien suivi les instructions ci-dessus mais que rien n'est écrit dans votre/vos fichier(s) de journalisation, et si votre système utilise SELinux, jetez un coup d’œil à la section [[Special:MyLanguage/SELinux#Debug_logging_file|logging sur la page SELinux]] pour contourner ce problème de contexte SELinux.}}

{{Tip|1=L'écriture de fichiers journaux dans le répertoire <code>/tmp</code> peut ne pas générer de fichier journal du tout, même si le répertoire /tmp est supposé être accessible en écriture à tous. Cela peut se produire si votre système utilise l'une des fonctionnalités systemd qui créent un répertoire virtuel /tmp pour ce processus. Si c'est le cas, configurez votre fichier journal à écrire dans un répertoire différent, comme <code>/var/log/mediawiki</code>}}

<span id="Structured_logging"></span>
==== Enregistrement structuré ====
{{MW 1.25|and after}}
La journalisation structurée vous permet d'inclure des champs dans vos enregistrements de journaux.
Voir {{ll|Structured logging}} pour plus d'informations.

{{Note|1=Vous aurez besoin de configurer un meilleur enregistreur (par exemple Monolog), pour collecter les champs supplémentaires.}}

<span id="JavaScript_error_logging"></span>
==== Jounaliser les erreurs JavaScript  ====
{{MW 1.36|and after}}
Voir la documentation du module ResourceLoader de {{ll|ResourceLoader/Core modules#mediawiki.errorLogger|mediawiki.errorLogger}}.

<span id="Statistics"></span>
=== Statistiques ===

La journalisation avancée côté client peut être effectuée avec {{ll|Extension:EventLogging}}, ce qui nécessite une configuration complexe et une inspection minutieuse des problèmes de confidentialité.

Le comptage simple de certains types d'événements est possible (depuis MediaWiki 1.25) en utilisant [https://github.com/etsy/statsd StatsD]. StatsD propose des compteurs cumulatifs, des jauges, des compteurs instantanés et des métriques de temps.

Exemple d'utilisation :

<syntaxhighlight lang="php">
$stats = $context->getStats();
$stats->increment( 'resourceloader.cache.hits' );
$stats->timing( 'resourceloader.cache.rtt', $rtt );
</syntaxhighlight>

Les métriques peuvent être envoyées à un serveur StatsD, qui peut être spécifié via la variable de configuration <code>wgStatsdServer</code>.
Si cette variable n'est pas définie, les métriques sont perdues.
Vous pouvez travailler avec StatsD localement (sans avoir besoin d'un serveur Graphite) en démarrant un serveur [https://github.com/etsy/statsd StatsD] et en le configurant avec le backend ''backends/console'', qui générera les métriques sur la console.

À partir de MediaWiki 1.25, <code>wfIncrStats()</code> est un raccourci pour la méthode <code>increment()</code> sur l'instance principale de <code>RequestContext::getStats()</code>.

<span id="Send_debug_data_to_an_HTML_comment_in_the_output"></span>
=== Envoyer des données de débogage à un commentaire HTML dans la sortie ===

Cela peut parfois être utile lorsqu'on aide un utilisateur final non technique. Il est plus sûr que d'exposer le fichier journal de débogage sur le web, car la sortie ne contient que des données privées pour l'utilisateur actuel. Mais il n'est pas idéal pour le développement car les données sont perdues en case d'erreur fatale ou de redirection. L'utilisation sur les sites de production n'est pas recommandée. Les commentaires de débogage révèlent des informations dans des vues de page qui pourraient potentiellement présenter des risques de sécurité.

<syntaxhighlight lang="php">
$wgDebugComments = true;
</syntaxhighlight>

* {{ll|Manual:$wgDebugComments|$wgDebugComments}}

<span id="Working_live_with_MediaWiki_objects"></span>
=== Travailler en direct avec des objets MediaWiki ===

{{ll|Manual:Eval.php|eval.php}} est un script interactif pour évaluer et interagir avec les objets et fonctions MediaWiki dans un environnement entièrement initialisé.

<pre>
 $ php maintenance/eval.php
 > print wfMessage("Recentchanges")->plain();
 Recent changes
</pre>

La machine virtuelle portable {{ll|MediaWiki-Vagrant}} intègre le shell PHP interactif <code>phpsh</code> (en utilisant Zend).

<span id="Callable_updates"></span>
=== Mises à jour appelables ===
Le code incorporé dans la fonction <code>DeferredUpdates::addCallableUpdate()</code>, comme <code>$rc->save()</code> dans <code>RecentChange.php</code>, n'est pas exécuté pendant la requête web, donc aucun message d'erreur ne sera affiché s'il échoue.
Pour le débogage, il peut être utile de supprimer temporairement le code de la fonction afin qu'il soit exécuté en direct.

<span id="Interactive_shell"></span>
=== Shell interactif ===

Vous pouvez utiliser {{ll|Manual:shell.php|shell.php}} comme un [[w:REPL|REPL]] PHP avec un accès complet aux variables internes de MédiaWiki.

<span id="Client_side_debugging_(JavaScript)"></span>
== Débogage côté client (JavaScript) ==
Wikipedia propose un riche ensemble d'outils pour déboguer le JavaScript côté client.
En plus des outils MediaWiki, d'autres techniques sont disponibles pour aider à diagnostiquer les interactions client.

Outils :

* {{ll|ResourceLoader}} propose [[Special:MyLanguage/ResourceLoader/Developing with ResourceLoader#Debugging|un moyen de s'assurer que JavaScript]] est facilement affichable par les outils côté client.
* Ouvrir la console de votre navigateur. De nombreux scripts Mediawiki côté client enregistrent les messages d'erreur sur la console à l'aide de ResourceLoader, qui fournit [[Special:MyLanguage/ResourceLoader/Modules#mediaWiki.log|un moyen orienté vers la sécurité]] pour se connecter à la console client. Au-delà de la fonction de journalisation JavaScript native, il fournit une vérification pour s'assurer qu'une console est disponible et que la journalisation ne produit pas sa propre erreur. [[Special:MyLanguage/ResourceLoader/Architecture#Debug_mode|ResourceLoader/Features#Debug_mode]] décrit également cette fonctionnalité.
* Les outils de navigation peuvent fournir une fonctionnalité native pour déboguer le script côté client.
* Les traceurs de réseau, comme [https://www.wireshark.org/ Wireshark] peuvent fournir un aperçu dans le script qui est fourni par une page.
* Vous pouvez ajouter <code>?debug=true</code> à votre URL comme dans https://www.mediawiki.org/wiki/MediaWiki?debug=true pour obtenir des informations plus détaillées pour le débogage via la console de votre navigateur

<span id="See_also"></span>
== Voir aussi ==
* {{ll|Manual:How to debug/Login problems}}
* {{ll|Manual:Profiling|Manual:Profiling}}
* ResourceLoader : [[Special:MyLanguage/ResourceLoader/Developing with ResourceLoader#Debugging|ResourceLoader/Developing with ResourceLoader#Debugging]]
* Toutes les variables de configuration liées au débogage/journalisation : [[Special:MyLanguage/Manual:Configuration settings#Debug/logging|Manuel:Paramètres de configuration#Debug/logging]]
* Astuce de débogage utile : <code>throw new MWException( 'foo' );</code> (meurt avec le message donné et imprime la pile des appels)
* {{ll|Manual:Errors and symptoms}}
* {{ll|Category:Debug variables}}
* [[:wikitech:Debugging in production]] - Débogage sur le groupe de production de Wikimedia
* {{ll|Help:Locating broken scripts}}

[[Category:MediaWiki development{{#translation:}}]]
[[Category:Log{{#translation:}}]]
[[Category:Debug{{#translation:}}]]