drupal-check

Check the code in a specific directory for deprecations

$ drupal-check [path/to/directory]

$ drupal-check [[-e|--exclude-dir]] [path/to/excluded_directory],[path/to/excluded_files/*.php] [path/to/directory]

$ drupal-check --no-progress [path/to/directory]

$ drupal-check [[-a|--analysis]] [path/to/directory]

drupal-check [OPTIONS] [PATH]

    Optional. The specific file or directory path to analyze. If omitted, it typically checks the current working directory or attempts to auto-discover the Drupal root.

-c, --config=CONFIG
    Specifies a custom path to a PHPStan configuration file (e.g., phpstan.neon) to tailor the analysis rules.

-r, --drupal-root=DRUPAL-ROOT
    Explicitly sets the path to the Drupal root directory. Useful when running drupal-check from a subdirectory or non-standard project structure.

-D, --deprecations
    Shows deprecation issues (this is the default behavior).

-n, --no-deprecations
    Disables the reporting of deprecation issues, focusing only on other general static analysis findings.

-a, --analysis
    Enables additional general static analysis checks, which might include potential bugs or code smells beyond just deprecations.

--triggered-deprecation-only
    Only shows deprecations that are actively triggered (require actual execution of the code path to be found), potentially reducing noise from unused code.

--json
    Outputs the analysis results in JSON format, suitable for programmatic consumption or CI/CD pipelines.

--error-format=FORMAT
    Specifies the output format for errors, e.g., pretty (default, human-readable), raw, or checkstyle (for integration with tools like Jenkins).

--memory-limit=LIMIT
    Sets the PHP memory limit for the command, useful for large codebases (e.g., 2G or -1 for no limit).

-v, -vv, -vvv
    Increases verbosity of messages. -vvv provides maximum verbosity, including debugging information.

-h, --help
    Displays the help message for the command.

drupal-check is a command-line tool that performs static analysis on Drupal projects, primarily to identify deprecated code usage and compatibility issues when upgrading between Drupal versions (e.g., Drupal 8 to 9, or 9 to 10). It leverages PHPStan along with Drupal-specific rules to scan your codebase without executing it.

The tool helps developers proactively find and fix code that will become incompatible or throw errors in newer Drupal versions, significantly aiding in the upgrade process. It checks for API changes, function removals, class deprecations, and other architectural shifts, providing actionable feedback. It's an essential tool for maintaining modern and upgrade-ready Drupal applications and can be integrated into development workflows and CI/CD pipelines.

While powerful, drupal-check performs static analysis, meaning it only inspects code structure and patterns, not runtime behavior. Therefore, it may produce false positives or miss issues that only manifest during execution. It's not a substitute for comprehensive testing (unit, integration, functional). Large codebases might require significant memory and processing time. Requires PHP (typically 7.4+ for modern Drupal) and Composer for installation and execution.

drupal-check is typically installed via Composer within your Drupal project to ensure version compatibility with your project's dependencies:

composer require --dev mglaman/drupal-check

Alternatively, for global access across multiple projects, you can install it globally, though this is less common for Drupal-specific tools due to potential dependency conflicts:

composer global require mglaman/drupal-check

After installation, you can run drupal-check from your Drupal root. To check a specific custom module, for example:

./vendor/bin/drupal-check web/modules/custom/mymodule

To analyze the entire codebase (including contributed modules and core), you might need to adjust your PHPStan configuration (e.g., in phpstan.neon or phpstan.neon.dist) to include or exclude specific paths and define analysis levels. It's highly recommended to integrate drupal-check into CI/CD pipelines to catch deprecations and compatibility issues early in the development cycle.

drupal-check was developed by Matt Glaman as a vital tool to assist with the significant upgrade paths between major Drupal versions, starting notably with Drupal 8 to 9. It grew out of the need for an efficient way to identify and address deprecated code patterns introduced by Drupal's continuous improvement and API changes. Its development is closely tied to the evolving needs of the Drupal community for smoother and more reliable upgrade processes, becoming an indispensable part of a Drupal developer's toolkit.

phpstan(1), phpcs(1), drush(1), composer(1)