PHP Mess Detector (phpmd) is a command line tool that analyzes PHP code and detects potential problems or signs of poor code quality. It provides a wide range of rulesets and formats to help developers identify and address issues in their codebase.

Use case 1: Display a list of available rulesets and formats

Code:

phpmd

Motivation: Before running a scan, it can be useful to know the available rulesets and formats provided by phpmd. This allows developers to choose the appropriate rulesets and specify the desired output format for the results.

Explanation: Running the phpmd command without any arguments will display a list of available rulesets and formats. This information is crucial for selecting the rulesets that best fit the project requirements and deciding on the format to generate the results.

Example output:

Available rulesets:
- cleancode
- codesize
- controversial
- ...

Use case 2: Scan a file or directory for problems using comma-separated rulesets

Code:

phpmd path/to/file_or_directory xml|text|html rulesets

Motivation: When working on PHP projects, it is important to ensure code quality by identifying potential issues such as unused variables, code duplication, or poor code design. Running the phpmd command with the specified file or directory and rulesets enables developers to scan their codebase for such problems.

Explanation: To perform a scan using phpmd, provide the path to the file or directory that needs to be analyzed. You can choose to output the results in XML, text, or HTML format by specifying the desired format. Additionally, you can specify the rulesets to be used during the scan, separating multiple rulesets with commas.

Example output:

------
path/to/file.php
------
Found 3 problems:

Problem 1:
Rule: SomeRule
Description: This is a description of the problem.
Priority: 2

Problem 2:
Rule: AnotherRule
Description: This is another description of the problem.
...

Use case 3: Specify the minimum priority threshold for rules

Code:

phpmd path/to/file_or_directory xml|text|html rulesets --minimumpriority priority

Motivation: To filter out less important or low-priority issues during a scan, developers can specify a minimum priority threshold. This helps focus on critical or higher-priority problems, making it easier to address them first.

Explanation: By using the --minimumpriority flag, developers can set a minimum priority level for the detected problems. Only the issues with a priority value greater than or equal to the specified threshold will be included in the scan results.

Example output:

Problem 1:
Rule: SomeRule
Description: This is a description of the problem.
Priority: 2

Problem 2:
Rule: AnotherRule
Description: This is another description of the problem.
Priority: 1

Use case 4: Include only the specified extensions in analysis

Code:

phpmd path/to/file_or_directory xml|text|html rulesets --suffixes extensions

Motivation: To restrict the analysis to specific file types or extensions, developers can use the --suffixes option. This helps in cases where the codebase contains various types of files, but the analysis focuses only on certain types.

Explanation: By providing the desired file extensions separated by commas after the --suffixes flag, developers can limit the analysis to only those file types. phpmd will only analyze files with extensions matching the specified ones.

Example output:

Scanning path/to/file.php...

Found 2 problems:

Problem 1:
Rule: SomeRule
...

Scanning path/to/file.js... (Excluded)

Scanning path/to/file.css... (Excluded)

Use case 5: Exclude the specified comma-separated directories

Code:

phpmd path/to/file_or_directory xml|text|html rulesets --exclude directory_patterns

Motivation: Sometimes, certain directories need to be excluded from the scan process. This can be useful when there are directories containing generated or third-party code that do not need to be analyzed.

Explanation: The --exclude option allows developers to exclude specific directories from the analysis. By providing the directory patterns separated by commas, phpmd will skip scanning those directories and their subdirectories.

Example output:

Scanning path/to/file1.php...
Scanning path/to/file2.php...
Scanning path/to/excluded_dir... (Excluded)

Use case 6: Output the results to a file instead of stdout

Code:

phpmd path/to/file_or_directory xml|text|html rulesets --reportfile path/to/report_file

Motivation: By default, phpmd outputs the results to the console (stdout). However, developers may prefer to save the results to a file for better analysis, sharing, or integration into the development pipeline.

Explanation: The --reportfile option allows developers to specify the file path where the analysis results will be saved. By providing the desired path after the --reportfile flag, phpmd will save the results to the specified file instead of printing them to the console.

Example output:

Results have been saved to path/to/report_file.xml

Use case 7: Ignore the use of warning-suppressive PHPDoc comments

Code:

phpmd path/to/file_or_directory xml|text|html rulesets --strict

Motivation: PHPMD can detect issues based on PHPDoc comments. However, if you want to focus only on critical problems and avoid false positives or intentional suppressions, you can use the --strict option to ignore warning-suppressive PHPDoc comments.

Explanation: When the --strict option is used, phpmd will consider all PHPDoc comments as potential issues, even if they are suppressing warnings or errors. This allows developers to focus on the actual code issues without being misled by intentional suppressions.

Example output:

Problem 1:
Rule: SomeRule
Description: This is a description of the problem.

Problem 2:
Rule: AnotherRule
Description: This is another description of the problem.
Priority: 3

Conclusion

The phpmd command provides a powerful set of options to scan and analyze PHP code. By understanding and using these options properly, developers can improve the quality of their codebase and address potential issues early on. Whether it’s selecting the appropriate rulesets, specifying the output format, or applying filters, phpmd offers flexibility and control for code analysis.