How to Use the Command 'psalm' (with examples)

Psalm is a static analysis tool designed for identifying errors in PHP applications. By providing a comprehensive analysis of PHP codebases, Psalm helps developers catch potential issues like type inconsistencies, availability of classes, and much more. This powerful tool enhances code quality and facilitates the maintenance and development of robust PHP applications. Below, we’ll explore different ways to harness the capabilities of Psalm through various use cases.

Use Case 1: Generate a Psalm Configuration

Code:

psalm --init

Motivation:

The psalm --init command is a great starting point for anyone new to using Psalm. By generating a default configuration file, this command sets up the basic settings needed to begin static analysis of a PHP project, providing a foundation to customize and optimize the analysis according to the project’s specific needs.

Explanation:

• psalm: This invokes the Psalm tool.
• --init: The --init option generates a default configuration file named psalm.xml in your project’s root directory. This XML file is essential as it contains various settings that dictate how Psalm performs its analysis.

Example Output:

Upon running the command, you might see the following output:

Config file created successfully at psalm.xml

This message confirms that the configuration file has been successfully created and is ready to be customized and used for your project’s analysis.

Use Case 2: Analyze the Current Working Directory

Code:

psalm

Motivation:

Running psalm without any additional arguments allows you to analyze the entire PHP codebase present within the current working directory. This is especially useful for getting a quick overview of potential issues early in the development process, ensuring that code changes don’t inadvertently introduce errors.

Explanation:

• psalm: Simply calling Psalm without options initiates a scan of all PHP files in the current directory based on the settings defined in the psalm.xml configuration file.

Example Output:

When executed, you might see output such as:

Scanning files...
No issues found!

This indicates the successful completion of the analysis with no errors detected within the given context.

Use Case 3: Analyze a Specific Directory or File

Code:

psalm path/to/file_or_directory

Motivation:

There are instances where you may only want to analyze a specific portion of your codebase, either a particular file or a directory. This targeted analysis reduces the time and resources required for scanning large projects and focuses attention on areas of interest, such as newly developed features or complex file structures undergoing refactoring.

Explanation:

• psalm: Starts the analysis process using Psalm.
• path/to/file_or_directory: This argument specifies the exact path to the PHP file or directory to be analyzed.

Example Output:

Running this command could yield output similar to:

Scanning path/to/file_or_directory...
1 issue found

This output shows that Psalm successfully conducted an analysis on the specified location and found an issue that needs to be addressed.

Use Case 4: Analyze a Project with a Specific Configuration File

Code:

psalm --config path/to/psalm.xml

Motivation:

Using custom configuration files allows developers to tailor Psalm’s behavior to their project’s unique requirements. By specifying a particular configuration file, you ensure that all analyses are consistent with the customized rules you put in place, such as excluding certain files, setting severity levels for warnings, and defining project-specific type assertions.

Explanation:

• psalm: Initiates the Psalm tool.
• --config: This flag denotes that you are specifying a custom configuration file for Psalm to use.
• path/to/psalm.xml: This is the path to the custom configuration file that Psalm should use for the current analysis.

Example Output:

The output might appear as follows:

Scanning files with custom configuration...
No issues found using path/to/psalm.xml

This indicates that the analysis, conducted according to custom configurations, detected no issues.

Use Case 5: Include Informational Findings in the Output

Code:

psalm --show-info

Motivation:

While many developers primarily focus on immediate errors, other informational findings can offer vital insights into code quality. By including informational notices in the analysis output, you can identify areas where improvements can be made, such as enhancing code clarity or eliminating potential risk factors that are not necessarily errors.

Explanation:

• psalm: Launches the Psalm analysis.
• --show-info: Adding this option ensures that the output includes informational and non-critical messages, giving a fuller picture of the codebase’s status.

Example Output:

Scanning files...
INFO: Some non-critical information
No issues found!

This output includes additional informational messages to help developers refine their code even further.

Use Case 6: Analyze a Project and Display Statistics

Code:

psalm --stats

Motivation:

Understanding the broader statistics of your codebase can immensely enhance the planning and execution of development tasks. Statistics like the number of issues found, types of errors, and file counts offer a high-level overview of the project’s current state, and can also track progress over time.

Explanation:

• psalm: Executes the Psalm tool.
• --stats: This option directs Psalm to present detailed statistics about the codebase in addition to performing the standard analysis.

Example Output:

Scanning files...
No issues found!
Statistics:
- Total files scanned: 100
- Total issues found: 0

This provides a snapshot of the project’s health, including statistics on the analyzed files.

Use Case 7: Analyze a Project in Parallel with 4 Threads

Code:

psalm --threads 4

Motivation:

Speed is critical in the software development lifecycle, especially when dealing with large codebases. Running Psalm analysis in parallel using multiple threads reduces the time it takes to complete the analysis, making it particularly beneficial for projects with significant numbers of files and complex structures.

Explanation:

• psalm: Activates the Psalm tool for analysis.
• --threads 4: Specifies that the analysis should utilize 4 threads for parallel processing, distributing the workload across available CPU cores to expedite execution.

Example Output:

Scanning files with 4 parallel threads...
No issues found!

This output emphasizes that analysis was successfully performed using multiple threads, optimizing performance without compromising result quality.

Conclusion:

Psalm is a versatile tool that provides deep insights into PHP applications through static analysis. Each use case demonstrates a different way to apply Psalm’s robust functionality, whether ensuring code quality with standard checks, utilizing custom configurations, or optimizing performance with parallel processing. With the help of Psalm, developers can mitigate risks, maintain high coding standards, and ultimately deliver more reliable software applications.