phpcs

PHP_CodeSniffer (phpcs) is a powerful static analysis tool that tokenizes PHP files and detects violations of defined coding standards. It serves as the industry standard for enforcing PHP coding conventions and maintaining consistent code quality across projects.

Key Features:

Multiple Coding Standards: Built-in support for PSR-1, PSR-2, PSR-12, PEAR, Zend, WordPress, Drupal, and many other standards
Tokenization Engine: Advanced PHP tokenizer that understands PHP syntax and language constructs for accurate analysis
Extensive Rule Set: Comprehensive checks for code formatting, naming conventions, documentation, and structural issues
Custom Standards: Create and configure custom coding standards tailored to project or organizational requirements
Detailed Reports: Multiple report formats including full, summary, checkstyle, CSV, JSON, and SARIF
Inline Suppression: Flexible system for suppressing specific violations using comment annotations
File Exclusions: Sophisticated ignore patterns for excluding files, directories, or specific code sections
Performance Optimized: Efficient scanning designed for large codebases with minimal memory usage

phpcs documentation

Version in MegaLinter: 3.13.2
Visit Official Web Site
See How to configure phpcs rules
- If custom phpcs.xml config file isn't found, phpcs.xml will be used
See How to disable phpcs rules in files
See How to ignore files and directories with phpcs
See Index of problems detected by phpcs

Configuration in MegaLinter

Enable phpcs by adding PHP_PHPCS in ENABLE_LINTERS variable
Disable phpcs by adding PHP_PHPCS in DISABLE_LINTERS variable

Variable	Description	Default value
PHP_PHPCS_ARGUMENTS	User custom arguments to add in linter CLI call Ex: `-s --foo "bar"`
PHP_PHPCS_COMMAND_REMOVE_ARGUMENTS	User custom arguments to remove from command line before calling the linter Ex: `-s --foo "bar"`
PHP_PHPCS_FILTER_REGEX_INCLUDE	Custom regex including filter Ex: `(src\\|lib)`	Include every file
PHP_PHPCS_FILTER_REGEX_EXCLUDE	Custom regex excluding filter Ex: `(test\\|examples)`	Exclude no file
PHP_PHPCS_CLI_LINT_MODE	Override default CLI lint mode - `file`: Calls the linter for each file - `list_of_files`: Call the linter with the list of files as argument - `project`: Call the linter from the root of the project	`list_of_files`
PHP_PHPCS_FILE_EXTENSIONS	Allowed file extensions. `"*"` matches any extension, `""` matches empty extension. Empty list excludes all files Ex: `[".py", ""]`	`[".php"]`
PHP_PHPCS_FILE_NAMES_REGEX	File name regex filters. Regular expression list for filtering files by their base names using regex full match. Empty list includes all files Ex: `["Dockerfile(-.+)?", "Jenkinsfile"]`	Include every file
PHP_PHPCS_PRE_COMMANDS	List of bash commands to run before the linter	None
PHP_PHPCS_POST_COMMANDS	List of bash commands to run after the linter	None
PHP_PHPCS_UNSECURED_ENV_VARIABLES	List of env variables explicitly not filtered before calling PHP_PHPCS and its pre/post commands	None
PHP_PHPCS_CONFIG_FILE	phpcs configuration file nameUse `LINTER_DEFAULT` to let the linter find it	`phpcs.xml`
PHP_PHPCS_RULES_PATH	Path where to find linter configuration file	Workspace folder, then MegaLinter default rules
PHP_PHPCS_DISABLE_ERRORS	Run linter but consider errors as warnings	`false`
PHP_PHPCS_DISABLE_ERRORS_IF_LESS_THAN	Maximum number of errors allowed	`0`
PHP_PHPCS_CLI_EXECUTABLE	Override CLI executable	`['phpcs']`

IDE Integration

Use phpcs in your favorite IDE to catch errors before MegaLinter !

IDE	Extension Name	Install
IDEA	phpcs	Visit Web Site
Sublime Text	sublime-phpcs	Visit Web Site
Sublime Text	SublimeLinter-phpcs	Visit Web Site
Visual Studio Code	vscode-phpcs

MegaLinter Flavors

This linter is available in the following flavors

Flavor	Description	Embedded linters
all	Default MegaLinter Flavor	126
cupcake	MegaLinter for the most commonly used languages	87
php	Optimized for PHP based projects	54

Behind the scenes

How are identified applicable files

File extensions: .php

How the linting is performed

phpcs is called once with the list of files as arguments (list_of_files CLI lint mode)

Example calls

phpcs myfile.php

phpcs --standard=phpcs.xml myfile.php

phpcs --standard=phpcs.xml mydir/ myfile.php

Help content



Usage:
  phpcs [options] <file|directory>

Scan targets:
  <file|directory>               One or more files and/or directories to check,
                                 space separated.
  -                              Check STDIN instead of local files and
                                 directories.
  --stdin-path=<stdinPath>       If processing STDIN, the file path that STDIN
                                 will be processed as.
  --file-list=<fileList>         Check the files and/or directories which are
                                 defined in the file to which the path is
                                 provided (one per line).
  --filter=<filter>              Check based on a predefined file filter. Use
                                 either the "GitModified" or "GitStaged" filter,
                                 or specify the path to a custom filter class.
  --ignore=<patterns>            Ignore files based on a comma-separated list of
                                 patterns matching files and/or directories.
  --extensions=<extensions>      Check files with the specified file extensions
                                 (comma-separated list). Defaults to
                                 php,inc/php,js,css.
                                 The type of the file can be specified using:
                                 ext/type; e.g. module/php,es/js.
  -l                             Check local directory only, no recursion.

Rule Selection Options:
  --standard=<standard>          The name of, or the path to, the coding
                                 standard to use. Can be a comma-separated list
                                 specifying multiple standards. If no standard
                                 is specified, PHP_CodeSniffer will look for a
                                 [.]phpcs.xml[.dist] custom ruleset file in the
                                 current directory and those above it.
  --sniffs=<sniffs>              A comma-separated list of sniff codes to limit
                                 the scan to. All sniffs must be part of the
                                 standard in use.
  --exclude=<sniffs>             A comma-separated list of sniff codes to
                                 exclude from the scan. All sniffs must be part
                                 of the standard in use.

  -i                             Show a list of installed coding standards.
  -e                             Explain a standard by showing the names of all
                                 the sniffs it includes.
  --generator=<generator>        Show documentation for a standard. Use either
                                 the "HTML", "Markdown" or "Text" generator.

Run Options:
  -a                             Run in interactive mode, pausing after each
                                 file.
  --bootstrap=<bootstrap>        Run the specified file(s) before processing
                                 begins. A list of files can be provided,
                                 separated by commas.
  --cache[=<cacheFile>]          Cache results between runs. Optionally,
                                 <cacheFile> can be provided to use a specific
                                 file for caching. Otherwise, a temporary file
                                 is used.
  --no-cache                     Do not cache results between runs (default).
  --parallel=<processes>         The number of files to be checked
                                 simultaneously. Defaults to 1 (no parallel
                                 processing).
                                 If enabled, this option only takes effect if
                                 the PHP PCNTL (Process Control) extension is
                                 available.

  -d <key[=value]>               Set the [key] php.ini value to [value] or set
                                 to [true] if value is omitted.
                                 Note: only php.ini settings which can be
                                 changed at runtime are supported.

Reporting Options:
  --report=<report(s)>           A comma-separated list of reports to print.
                                 Available reports: "full", "xml", "checkstyle",
                                 "csv", "json", "junit", "emacs", "source",
                                 "summary", "diff", "svnblame", "gitblame",
                                 "hgblame", "notifysend" or "performance".
                                 Or specify the path to a custom report class.
                                 By default, the "full" report is displayed.
  --report-file=<reportFile>     Write the report to the specified file path.
  --report-<report>=<reportFile> Write the report specified in <report> to the
                                 specified file path.
  --report-width=<reportWidth>   How many columns wide screen reports should be.
                                 Set to "auto" to use current screen width,
                                 where supported.
  --basepath=<basepath>          Strip a path from the front of file paths
                                 inside reports.

  -w                             Include both warnings and errors (default).
  -n                             Do not include warnings. Shortcut for
                                 "--warning-severity=0".
  --severity=<severity>          The minimum severity required to display an
                                 error or warning. Defaults to 5.
  --error-severity=<severity>    The minimum severity required to display an
                                 error. Defaults to 5.
  --warning-severity=<severity>  The minimum severity required to display a
                                 warning. Defaults to 5.

  -s                             Show sniff error codes in all reports.
  --ignore-annotations           Ignore all "phpcs:..." annotations in code
                                 comments.
  --colors                       Use colors in screen output.
  --no-colors                    Do not use colors in screen output (default).
  -p                             Show progress of the run.
  -q                             Quiet mode; disables progress and verbose
                                 output.
  -m                             Stop error messages from being recorded. This
                                 saves a lot of memory but stops many reports
                                 from being used.

Configuration Options:
  --encoding=<encoding>          The encoding of the files being checked.
                                 Defaults to "utf-8".
  --tab-width=<tabWidth>         The number of spaces each tab represents.

  Default values for a selection of options can be stored in a user-specific
  CodeSniffer.conf configuration file.
  This applies to the following options: "default_standard", "report_format",
  "tab_width", "encoding", "severity", "error_severity", "warning_severity",
  "show_warnings", "report_width", "show_progress", "quiet", "colors", "cache",
  "parallel", "installed_paths", "php_version", "ignore_errors_on_exit",
  "ignore_warnings_on_exit".
  --config-show                  Show the configuration options which are
                                 currently stored in the applicable
                                 CodeSniffer.conf file.
  --config-set <key> <value>     Save a configuration option to the
                                 CodeSniffer.conf file.
  --config-delete <key>          Delete a configuration option from the
                                 CodeSniffer.conf file.
  --runtime-set <key> <value>    Set a configuration option to be applied to the
                                 current scan run only.

Miscellaneous Options:
  -h, -?, --help                 Print this help message.
  --version                      Print version information.
  -v                             Verbose output: Print processed files.
  -vv                            Verbose output: Print ruleset and token output.
  -vvv                           Verbose output: Print sniff processing
                                 information.

Installation on mega-linter Docker image

Dockerfile commands :

# Parent descriptor install
RUN update-alternatives --install /usr/bin/php php /usr/bin/php84 110
COPY --from=composer/composer:2-bin /composer /usr/bin/composer
ENV PATH="/root/.composer/vendor/bin:${PATH}"
ENV PHP_CS_FIXER_IGNORE_ENV=true
# Linter install
# renovate: datasource=packagist depName=squizlabs/php_codesniffer
ARG PHP_SQUIZLABS_PHP_CODESNIFFER_VERSION=3.13.2
# renovate: datasource=packagist depName=bartlett/sarif-php-converters
ARG PHP_BARTLETT_SARIF_PHP_CONVERTERS_VERSION=1.2.0
RUN GITHUB_AUTH_TOKEN="$(cat /run/secrets/GITHUB_TOKEN)" && export GITHUB_AUTH_TOKEN && composer global require squizlabs/php_codesniffer:${PHP_SQUIZLABS_PHP_CODESNIFFER_VERSION} bartlett/sarif-php-converters:${PHP_BARTLETT_SARIF_PHP_CONVERTERS_VERSION}