Utilisation (Previous) (Next) Configuration Options
View this page in Last updated: Sun, 28 Sep 2008
English | Dutch | French | German | Hungarian | Japanese | Polish | Spanish | Plain HTML

Utilisation avancée

Utilisation avancée -- Informations pour une utilisation poussée PHP_CodeSniffer

Spécifier les extentions de fichiers

Par défaut, PHP_CodeSniffer ne va vérifier que les fichiers trouvés avec les extentions .inc ou .php. Parfois, cela signifie que PHP_CodeSniffer ne vérifie pas assez de vos fichiers. Parfois, l'inverse est vrai. PHP_CodeSniffer permet d'indiquer la liste des extentions valides en utilisant l'argument --extensions. Les extensions sont à séparer par des virgules.

Exemple 58-1. Ne vérifier QUE les fichiers .php


$ phpcs --extensions=php /path/to/code

Exemple 58-2. Vérifier les fichiers avec les extentions .php, .inc et .lib 


$ phpcs --extensions=php,inc,lib /path/to/code

Note : Si vous demandez à PHP_CodeSniffer de vérifier un fichier en particulier à la place d'un répertoire entier, la contrainte sur l'extension sera ignorée. Le fichier sera vérifié même s'il n'a pas l'extension spécifiée ou considérée par défaut.

Dans l'exemple suivant, le fichier main.inc sera vérifié par PHP_CodeSniffer à l'aide de l'argument --extensions qui spécifie que seuls les fichiers .php peuvent être vérifié.

Exemple 58-3. Extension ignored when checking specific file


$ phpcs --extensions=php /path/to/code/main.inc

Note : The ignoring of file extensions for specific files is a feature of PHP_CodeSniffer and is the only way to check files without an extension. If you check an entire directory of files, all files without extensions will be ignored, so you must check each of these file separately.

Ignorer des fichiers et des dossiers

Parfois vous voudrez que PHP_CodeSniffer s'exécute sur un très grand nombre de fichiers, mais vous voulez ignorer quelques dossiers et fichiers. L'argument de commande --ignore peut être employé pour dire à PHP_CodeSniffer d'ignorer les dossiers et fichiers correspondants à un ou plusieurs modèles.

Dans l'exemple suivant, PHP_CodeSniffer va ignorer tous les fichier à l'intérieur du package se trouvant dans les répertoires tests et data. C'est utile si vous vérifiez un package de PEAR mais sans vouloir vérifier que vos fichiers de test ou de données se conforment à votre norme de codage.

Exemple 58-4. Ignoring test and data files


$ phpcs --ignore=*/tests/*,*/data/* /path/to/code

Remplacer les tabulation par des espaces

Most of the sniffs written for PHP_CodeSniffer do not support the usage of tabs for indentation and alignment. You can write your own sniffs that check for tabs instead of spaces, but you can also get PHP_CodeSniffer to convert your tabs into spaces before a file is checked. This allows you to use the existing space-based sniffs on your tab-based files.

In the following example, PHP_CodeSniffer will replace all tabs in the files being checked with between 1 and 4 spaces, depending on the column the tab indents to.

Exemple 58-5. Conversion des tabulations en espaces


$ phpcs --tab-width=4 /path/to/code

Afficher un rapport XML

PHP_CodeSniffer can output an XML report to allow you to parse the output easily and use the results in your own scripts. To print an XML report, use the --report=xml command line argument. The output will look like this:

Exemple 58-6. Sample PHP_CodeSniffer XML output

$ phpcs --report=xml /path/to/code

<?xml version="1.0" encoding="UTF-8"?>
<phpcs version="1.0.0">
 <file name="/path/to/code/myfile.php" errors="5" warnings="1">
  <error line="2" column="1">Missing file doc comment</error>
  <error line="20" column="43">PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;</error>
  <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error>
  <warning line="47" column="20">Equals sign not aligned with surrounding assignments</warning>
  <error line="51" column="4">Missing function doc comment</error>
  <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error>
 </file>
</phpcs>

As with the full report, you can suppress the printing of warnings with the -n command line argument.

Exemple 58-7. Sample PHP_CodeSniffer XML output with no warnings

$ phpcs -n --report=xml /path/to/code

<?xml version="1.0" encoding="UTF-8"?>
<phpcs version="1.0.0">
 <file name="/path/to/code/myfile.php" errors="5" warnings="0">
  <error line="2" column="1">Missing file doc comment</error>
  <error line="20" column="43">PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;</error>
  <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error>
  <error line="51" column="4">Missing function doc comment</error>
  <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error>
 </file>
</phpcs>

Printing a Checkstyle Report

PHP_CodeSniffer can output an XML report similar to the one produced by Checkstyle, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the --report=checkstyle command line argument. The output will look like this:

Exemple 58-8. Sample PHP_CodeSniffer Checkstyle output

$ phpcs --report=checkstyle /path/to/code

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
 <file name="/path/to/code/myfile.php">
  <error line="2" column="1" severity="error" message="Missing file doc comment"/>
  <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;"/>
  <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/>
  <error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments"/>
  <error line="51" column="4" severity="error" message="Missing function doc comment"/>
  <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/>
 </file>
</checkstyle>

As with the full report, you can suppress the printing of warnings with the -n command line argument.

Exemple 58-9. Sample PHP_CodeSniffer Checkstyle output with no warnings

$ phpcs -n --report=checkstyle /path/to/code

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
 <file name="/path/to/code/myfile.php">
  <error line="2" column="1" severity="error" message="Missing file doc comment"/>
  <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;"/>
  <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/>
  <error line="51" column="4" severity="error" message="Missing function doc comment"/>
  <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/>
 </file>
</checkstyle>

Afficher un rapport CSV

PHP_CodeSniffer peut sortir un rapport au format CSV pour permettre un parsing facile et utiliser le résultat dans vos propres scripts. Pour sortir un rapport CSV, utilisez l'argument de ligne de commande --report=csv. L'affichage devrait ressembler à ceci:

Exemple 58-10. Exemple de rapport CSV de PHP_CodeSniffer

$ phpcs --report=csv /path/to/code

File,Line,Column,Severity,Message
"/path/to/code/myfile.php",2,1,error,"Missing file doc comment"
"/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\""
"/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1"
"/path/to/code/myfile.php",47,20,warning,"Equals sign not aligned with surrounding assignments"
"/path/to/code/myfile.php",51,4,error,"Missing function doc comment"
"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6"

Comme pour le rapport complet, vous pouvez supprimer l'affichage des warnings avec l'argument -n.

Exemple 58-11. Exemple de rapport CSV de PHP_CodeSniffer sans warnings

$ phpcs -n --report=csv /path/to/code

File,Line,Column,Severity,Message
"/path/to/code/myfile.php",2,1,error,"Missing file doc comment"
"/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\""
"/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1"
"/path/to/code/myfile.php",51,4,error,"Missing function doc comment"
"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6"

Note : The first row of the CSV output defines the order of information. When using the CSV output, please parse this header row to determine the order correctly as the format may change over time or new information may be added.

Setting Configuration Options

PHP_CodeSniffer has some configuration options that can be set. Individual coding standards may also require configuration options to be set before functionality can be used. View a full list of configuration options.

To set a configuration option, use the --config-set command line argument.

Exemple 58-12. Setting a configuration option


$ phpcs --config-set <option> <value>

Déactiver une option de configuration

PHP_CodeSniffer permet de déactiver une option de configuration, pour lui faire reprendre sa valeur par défaut. View a full list of configuration options.

Pour déactiver une option de configuration, utilisez l'argument --config-delete.

Exemple 58-13. Déactiver une option de configuration


$ phpcs --config-delete <option>

Viewing Configuration Options

To view the currently set configuration options, use the --config-show command line argument.

Exemple 58-14. Viewing configuration options


$ phpcs --config-show
Array
(
    [default_standard] => PEAR
    [zend_ca_path] => /path/to/ZendCodeAnalyzer
)

Printing Verbose Tokeniser Output

Note : Cette fonctionnalité est proposée seulement pour debugger. L'utilisation de cette fonctionnalité augmente terriblement la taille de ce qui sera affiché et le temps d'éxécution du script.

PHP_CodeSniffer propose différents niveaux de quantité d'information à afficher. Le second niveau (indiqué par l'argument -vv) affichera toutes les informations affichée au niveau (file specific token and line counts with running times) as well as verbose tokeniser output.

The output of the PHP_CodeSniffer tokeniser shows the step-by-step creation of the scope map and the level map.

Le Scope Map

Le scope map est plus facile à expliquer avec un exemple. Pour le fichier suivant: 


<?php
if ($condition) {
    echo 'La condition était vraie';
}
?>

L'affichage du scope map sera:

Exemple 58-15. Exemple d'affichage de scope map

*** START SCOPE MAP ***
Start scope map at 1: T_IF => if
Process token 2 []: T_WHITESPACE =>  
Process token 3 []: T_OPEN_PARENTHESIS => (
Process token 6 []: T_WHITESPACE =>  
Process token 7 []: T_OPEN_CURLY_BRACKET => {
=> Found scope opener for 1 (T_IF)
Process token 8 [opener:7;]: T_WHITESPACE => \n
Process token 9 [opener:7;]: T_WHITESPACE =>     
Process token 10 [opener:7;]: T_ECHO => echo
Process token 11 [opener:7;]: T_WHITESPACE =>  
Process token 12 [opener:7;]: T_CONSTANT_ENCAPSED_STRING => 'La condition était vraie'
Process token 13 [opener:7;]: T_SEMICOLON => ;
Process token 14 [opener:7;]: T_WHITESPACE => \n
Process token 15 [opener:7;]: T_CLOSE_CURLY_BRACKET => }
=> Found scope closer for 1 (T_IF)
*** END SCOPE MAP ***

The scope map output above shows the following pieces of information about the file:

  • A scope token, if, a été trouvé comme lexème 1 (Notez que le lexème 0 est le tag d'ouverture PHP).

  • L'ouverture pour l'instruction if, l'accolade ouvrante, a été trouvé au lexème 7.

  • La fermeture de l'instruction if, l'accolade fermante, a été trouvée au lexème 15.

  • Tokens 8 - 15 are all included in the scope set by the scope opener at token 7, the open curly brace. This indicates that these tokens are all within the if statement.

The scope map output is most useful when debugging PHP_CodeSniffer's scope map, which is critically important to the successful checking of a file, but is also useful for checking the type of a particular token. For example, if you are unsure of the token type for an opening curly brace, the scope map output shows you that the type is T_OPEN_CURLY_BRACKET and not, for example, T_OPEN_CURLY_BRACE.

La Level Map

La level map est plus facile à expliquer avec un exemple. Pour le fichier suivant: 


<?php
if ($condition) {
    echo 'La condition était vraie';
}
?>

L'affichage du level map est:

Exemple 58-16. Exemple d'affichage de level map

*** START LEVEL MAP ***
Process token 0 on line 1 [lvl:0;]: T_OPEN_TAG => <?php\n
Process token 1 on line 2 [lvl:0;]: T_IF => if
Process token 2 on line 2 [lvl:0;]: T_WHITESPACE =>  
Process token 3 on line 2 [lvl:0;]: T_OPEN_PARENTHESIS => (
Process token 4 on line 2 [lvl:0;]: T_VARIABLE => $condition
Process token 5 on line 2 [lvl:0;]: T_CLOSE_PARENTHESIS => )
Process token 6 on line 2 [lvl:0;]: T_WHITESPACE =>  
Process token 7 on line 2 [lvl:0;]: T_OPEN_CURLY_BRACKET => {
=> Found scope opener for 1 (T_IF)
    * level increased *
    * token 1 (T_IF) added to conditions array *
    Process token 8 on line 2 [lvl:1;conds;T_IF;]: T_WHITESPACE => \n
    Process token 9 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE =>     
    Process token 10 on line 3 [lvl:1;conds;T_IF;]: T_ECHO => echo
    Process token 11 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE =>  
    Process token 12 on line 3 [lvl:1;conds;T_IF;]: T_CONSTANT_ENCAPSED_STRING => 'La condition était vraie'
    Process token 13 on line 3 [lvl:1;conds;T_IF;]: T_SEMICOLON => ;
    Process token 14 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE => \n
    Process token 15 on line 4 [lvl:1;conds;T_IF;]: T_CLOSE_CURLY_BRACKET => }
    => Found scope closer for 7 (T_OPEN_CURLY_BRACKET)
    * token T_IF removed from conditions array *
    * level decreased *
Process token 16 on line 4 [lvl:0;]: T_WHITESPACE => \n
Process token 17 on line 5 [lvl:0;]: T_CLOSE_TAG => ?>\n
*** END LEVEL MAP ***

The level map output above shows the following pieces of information about the file:

  • A scope opener, an open curly brace, was found at token 7 and opened the scope for an if statement, defined at token 1.

  • Les lexèmes 8 - 15 are all included in the scope set by the scope opener at token 7, the open curly brace. All these tokens are at level 1, indicating that they are enclosed in 1 scope condition, and all these tokens are enclosed in a single condition; an if statement.

The level map is most commonly used to determine indentation rules (eg. a token 4 levels deep requires 16 spaces of indentation) or to determine if a particular token is within a particular scope (eg. a function keyword is within a class scope, making it a method).

Afficher les détails du traîtment des lexèmes

Note : Cette fonctionnalité est juste fournie pour du debuging L'utilisation de cette fonctionnalité augmente terriblement le temps d'éxécution du script et la taille de l'affichage généré.

PHP_CodeSniffer dispose de plusieurs niveau de détails. Niveau 3 (indicated by the command line argument -vvv) will print all verbosity information for Niveau 1 (file specific token and line counts with running times), Niveau 2 (tokeniser output) as well as token processing output with sniff running times.

Le traitement des lexèmes est aussi plus facile à expliquer par l'exemple. For the following file: 


<?php
if ($condition) {
    echo 'La condition était vraie';
}
?>

The token processing output is:

Exemple 58-17. Sample token processing output

*** START TOKEN PROCESSING ***
Process token 0: T_OPEN_TAG => <?php\n
    Processing PEAR_Sniffs_Commenting_FileCommentSniff... DONE in 0.001 seconds
    Processing PEAR_Sniffs_Files_LineLengthSniff... DONE in 0.0004 seconds
    Processing PEAR_Sniffs_PHP_DisallowShortOpenTagSniff... DONE in 0.0001 seconds
Process token 1: T_IF => if
    Processing PEAR_Sniffs_ControlStructures_ControlSignatureSniff... DONE in 0.0008 seconds
    Processing PEAR_Sniffs_WhiteSpace_ScopeClosingBraceSniff... DONE in 0.0248 seconds
    Processing PEAR_Sniffs_WhiteSpace_ScopeIndentSniff... DONE in 0.0004 seconds
Process token 2: T_WHITESPACE =>  
Process token 3: T_OPEN_PARENTHESIS => (
Process token 4: T_VARIABLE => $condition
Process token 5: T_CLOSE_PARENTHESIS => )
Process token 6: T_WHITESPACE =>  
Process token 7: T_OPEN_CURLY_BRACKET => {
Process token 8: T_WHITESPACE => \n
Process token 9: T_WHITESPACE =>     
Process token 10: T_ECHO => echo
Process token 11: T_WHITESPACE =>  
Process token 12: T_CONSTANT_ENCAPSED_STRING => 'La condition était vraie'
Process token 13: T_SEMICOLON => ;
Process token 14: T_WHITESPACE => \n
Process token 15: T_CLOSE_CURLY_BRACKET => }
Process token 16: T_WHITESPACE => \n
Process token 17: T_CLOSE_TAG => ?>\n
*** END TOKEN PROCESSING ***

Every token processed is shown, along with its ID, type and contents. For each token, all sniffs that were executed on the token are displayed, along with the running time.

For example, the output above shows us that token 1, an if keyword, had 3 sniffs executed on it; the ControlSignature sniff, the ScopeClosingBrace sniff and the ScopeIndent sniff. Each was executed fairly quickly, but the slowest was the ScopeClosingBrace sniff, taking 0.0248 seconds to process that token.

The other interesting piece of information we get from the output above is that only 2 tokens in the whole file had sniffs executed on them; tokens 0 and 1. This is normal behavior for PHP_CodeSniffer as most sniffs listen for a very specific and rarely used token and then execute on it and a number of tokens following it.

For example, the ScopeIndentSniff executes on the if statement's token only, but actually checks the indentation of every line within the if statement. The sniff uses the scope map to find all tokens within the if statement.

Utilisation (Previous) (Next) Configuration Options
Download Documentation Last updated: Sun, 28 Sep 2008
Do you think that something on this page is wrong? Please file a bug report or add a note.
User Notes:
There are no user contributed notes for this page.