composer-require-checker

Analyze a Composer JSON file

$ composer-require-checker check [path/to/composer.json]

$ composer-require-checker check --config-file [path/to/config.json] [path/to/composer.json]

composer-require-checker check [options] [<path>]
composer-require-checker <command> [options]

check
    Performs the dependency analysis. This is the default subcommand if no command is specified.

<path>
    The path to the project directory to analyze. Defaults to the current working directory.

--strict
    Fails if any package is declared but not used, or if any package is used but not declared. This enforces stricter dependency hygiene.

--dry-run
    Performs the check but always exits with status code 0, regardless of whether issues are found. Useful for CI logs without failing builds.

--ignore-dev
    Do not check require-dev dependencies for usage in the production code. This prevents reporting unused dev dependencies as issues.

--ignore-linter
    Exclude specific paths that might be generated by linters or code formatters (e.g., .php-cs-fixer/.php-cs-fixer.cache).

--ignore-php
    Do not report issues related to the 'php' platform requirement in composer.json.

--path-to-composer-json <path>
    Specify the exact path to the composer.json file to be analyzed.

--composer-vendor-dir <path>
    Specify the path to the Composer vendor directory, if it's not the default ./vendor.

--exclude <path>
    Exclude specific files or directories from analysis. This option can be used multiple times to exclude several paths.

--config <path>
    Path to a custom configuration file (e.g., composer-require-checker.json) for advanced settings.

--dump-configuration
    Dumps the default configuration to standard output. Useful for creating a custom config file.

-v, --verbose
    Increase the verbosity of messages. Can be used multiple times for more detailed output (e.g., -vv, -vvv).

--version
    Display the application version information.

-h, --help
    Display help for the command or a specific subcommand.

composer-require-checker is a command-line tool designed for PHP projects managed with Composer. Its primary function is to analyze your project's source code and compare the packages it actually uses against the require section of your composer.json file. It identifies two main issues: packages declared in composer.json but never used in the code, and packages used in the code but not declared in composer.json. This helps maintain a clean composer.json, reduce project size by removing unnecessary dependencies, and prevent runtime errors due to missing packages. By enforcing dependency hygiene, it contributes to better project maintainability and performance.

• Relies primarily on static analysis of PHP code; dynamic usage (e.g., via eval(), variable functions, or complex class loading mechanisms) might not be fully detected, potentially leading to false negatives (packages used but not reported as such).
• It checks direct usages. If a package is pulled in as a transitive dependency and then used without being explicitly in your composer.json's require section, it might be reported as "used but not declared".
• For optimal results and to manage exceptions, it is highly recommended to use a dedicated configuration file (e.g., composer-require-checker.json) in complex projects.

composer-require-checker is typically installed via Composer.
To install it globally and make it available system-wide:
composer global require maglnet/composer-require-checker
Alternatively, to install it as a development dependency for a specific project:
composer require --dev maglnet/composer-require-checker
When installed as a project dependency, the executable is found within your project's vendor/bin/ directory (e.g., ./vendor/bin/composer-require-checker).

For advanced usage and to customize its behavior, composer-require-checker supports a configuration file, typically named composer-require-checker.json, placed in the project root. This JSON file allows you to specify:

• Paths to exclude from analysis (e.g., test files, generated code).
• Packages to explicitly ignore (e.g., specific polyfills).
• Custom 'symbol providers' for very specific use cases.

composer-require-checker was developed to address the common problem of "dependency creep" in PHP projects. As projects evolve, features are added and removed, often leaving behind unused packages in composer.json, which leads to larger project sizes, slower Composer operations, and potential security vulnerabilities from outdated dependencies. The tool provides an automated, static analysis-based approach to identify these discrepancies. Its development has focused on robust analysis capabilities and flexible configuration options to integrate seamlessly into various project structures and CI/CD pipelines, promoting better dependency hygiene in PHP development.

composer(1), php(1), php-cs-fixer(1)