Use Case 1: Generating a .phan/config.php file in the current directory

To generate a .phan/config.php file in the current directory, you can use the --init option with the phan command:

phan --init

Motivation:

Generating a configuration file is the first step in setting up Phan for static analysis. The .phan/config.php file allows you to customize Phan’s behavior according to your project’s needs.

Explanation:

The --init option instructs Phan to generate a default .phan/config.php file in the current directory. This configuration file can be further customized to specify include and exclude directories, enable or disable specific plugins, and set various analysis options.

Example Output:

After running the above command, a .phan/config.php file will be created in the current directory containing the default configuration options.

Use Case 2: Generating a Phan configuration file with a specific level

To generate a Phan configuration file with a specific level, you can use the --init option along with the --init-level option:

phan --init --init-level level

Replace level with a number between 1 and 5, where 1 represents the strictest level and 5 represents the least strict level.

Motivation:

Different projects have different levels of tolerance for potential issues in the codebase. Specifying a specific level during the generation of the configuration file allows you to set the desired level of strictness for your project’s static analysis.

Explanation:

The --init-level option allows you to specify the desired strictness level while generating the Phan configuration file using the --init option. The strictness level determines which types of potential issues Phan will report. A lower strictness level will result in fewer false-positive or less severe warnings.

Example Output:

By running the above command, a .phan/config.php file will be generated in the current directory with the specified strictness level.

Use Case 3: Analyzing the current directory

To analyze the files in the current directory, you can simply run the phan command without any additional options:

phan

Motivation:

Analyzing the current directory allows you to perform static analysis on all PHP files within the current working directory and its subdirectories. This is particularly useful when you want to analyze the entire project in one go.

Explanation:

Running the phan command without any additional options instructs Phan to analyze all PHP files within the current directory and its subdirectories. Phan will use the .phan/config.php file in the current directory (or in a different specified location) for its configuration.

Example Output:

Upon running the above command, Phan will analyze all the PHP files in the current directory and display the analysis results, including any potential issues found.

Use Case 4: Analyzing one or more directories

To analyze one or more directories, you can use the --directory option with the phan command:

phan --directory path/to/directory --directory path/to/another_directory

Replace path/to/directory and path/to/another_directory with the actual paths to the directories you want to analyze.

Motivation:

In larger projects, you may want to perform static analysis on specific directories rather than the entire project. Analyzing only selected directories can save time and focus the analysis on the areas that are most relevant to your current task.

Explanation:

The --directory option allows you to specify one or more directories to be analyzed by Phan. You can provide multiple --directory options to analyze multiple directories simultaneously. Phan will recursively analyze all PHP files within the specified directories.

Example Output:

Upon executing the above command, Phan will analyze all the PHP files within the specified directories and display the analysis results for each directory separately.

Use Case 5: Specifying a config file

To specify a custom configuration file for Phan, you can use the --config-file option with the phan command:

phan --config-file path/to/config.php

Replace path/to/config.php with the actual path to your custom configuration file.

Motivation:

Having the ability to use a custom configuration file allows you to fine-tune Phan’s behavior according to your project’s unique requirements. You may want to enable or disable specific plugins, redefine include and exclude directories, or adjust various analysis options.

Explanation:

The --config-file option allows you to specify the path to a custom configuration file for Phan. The custom configuration file should be a valid PHP script that returns an array of configuration options. By default, Phan looks for a configuration file named .phan/config.php in the current directory. Specifying a custom configuration file allows you to use a different file and location.

Example Output:

Upon running the above command, Phan will use the specified custom configuration file for the static analysis. The analysis results will reflect the configuration options specified in the custom file.

Use Case 6: Specifying the output mode

To specify the output mode for the analysis results, you can use the --output-mode option with the phan command:

phan --output-mode text|verbose|json|csv|codeclimate|checkstyle|pylint|html

Replace text|verbose|json|csv|codeclimate|checkstyle|pylint|html with the desired output mode.

Motivation:

Phan provides various output modes to suit different needs. Choosing the appropriate output mode allows you to consume the analysis results in the most convenient and compatible format for your specific use case.

Explanation:

The --output-mode option allows you to specify the desired output mode for the analysis results produced by Phan. Phan supports the following output modes:

• text (default): Output the results as plain text.
• verbose: Output the results with additional details.
• json: Output the results in JSON format.
• csv: Output the results in CSV format.
• codeclimate: Output the results in the Code Climate format.
• checkstyle: Output the results in the Checkstyle format.
• pylint: Output the results in the Pylint format.
• html: Output the results as an HTML report.

Example Output:

Running the above command with the desired output mode will produce the analysis results in the specified format.

Use Case 7: Specifying the number of parallel processes

To specify the number of parallel processes for the analysis, you can use the --processes option with the phan command:

phan --processes number_of_processes

Replace number_of_processes with the desired number of parallel processes.

Motivation:

Adjusting the number of parallel processes can significantly impact the speed of the analysis. By utilizing multiple processes, the analysis can be distributed across CPU cores, leading to faster execution and shorter analysis times.

Explanation:

The --processes option allows you to specify the number of parallel processes to be used for the analysis. Phan will attempt to parallelize the analysis to utilize the specified number of processes, taking advantage of multi-core systems. A higher number of processes can lead to faster analysis times but may also increase resource usage.

Example Output:

Upon running the above command with the desired number of processes, Phan will perform the analysis using the specified number of parallel processes. The output will contain the analysis results based on the configuration and specified output mode.

Conclusion

In this article, we explored several different use cases of the phan command, a static analysis tool for PHP. We learned how to generate a configuration file, analyze directories, specify custom configurations, and control various aspects of the analysis process. By understanding these different use cases and their associated options, you can leverage Phan effectively for static analysis of PHP code in your projects.