PHPStan: Elevate Your PHP Code Quality with Static Analysis

Managing code quality and ensuring error-free development can be challenging in the PHP ecosystem, where dynamic typing is prevalent. PHPStan is a static analysis tool tailored for PHP that’s designed to help developers catch bugs and potential issues before they even run their code. Through static analysis, PHPStan allows developers to write more reliable, maintainable, and robust code by catching errors early in development. In this post, we’ll explore what PHPStan is, who should use it, how to incorporate it into your development workflow, and some exciting updates in PHPStan 2.0.

---

What is PHPStan?

PHPStan is a static analysis tool for PHP that inspects your code and identifies issues without executing it. Unlike runtime testing, static analysis doesn’t require your code to run, which allows PHPStan to find issues and potential bugs in real time as you write code. This is particularly useful in PHP, where the dynamic typing system can sometimes allow issues to go unnoticed until runtime.

PHPStan operates by analyzing types, variables, function calls, and other code patterns to find inconsistencies or potential bugs. It helps identify errors such as:

• Calling a method on a variable that could be null
• Accessing undefined properties
• Passing incorrect types to a function
• Using undefined variables or classes

While these issues might otherwise be caught at runtime (if they’re caught at all), PHPStan catches them during development, creating a faster feedback loop for developers and leading to cleaner, more robust code.

---

Why Use PHPStan?

Using PHPStan brings many benefits, including:

1. Early Detection of Bugs: PHPStan helps you identify issues before they reach production, preventing runtime errors that can affect your application’s reliability and performance.
2. Improved Code Quality: By enforcing stricter type-checking and coding practices, PHPStan leads to more maintainable, readable code.
3. Confidence in Refactoring: Refactoring code becomes less intimidating when you have a tool like PHPStan validating your changes, ensuring that you aren’t introducing new issues.
4. Consistency Across Teams: PHPStan enforces coding standards and best practices, which can help teams create more consistent codebases, especially in collaborative environments.

---

Who Should Use PHPStan?

PHPStan is a great tool for PHP developers at all levels. However, it’s particularly valuable for:

• Mid to Senior PHP Developers: More experienced developers will appreciate the extra level of polish and control PHPStan provides, especially for large codebases.
• Teams and Organizations: PHPStan helps teams enforce consistent coding practices, making it easier for multiple developers to collaborate and understand each other’s work.
• Open-Source Projects: For open-source maintainers, PHPStan can help to maintain high code quality standards across contributions, ensuring that new code doesn’t introduce issues.
• Projects with Legacy Code: PHPStan can gradually help clean up and modernize legacy codebases, catching outdated or problematic patterns and ensuring they adhere to current best practices.

While PHPStan has a learning curve and might initially feel strict, it pays off quickly by improving the quality and maintainability of any PHP project.

---

How to Use PHPStan

PHPStan is relatively straightforward to set up and start using in your projects. Here’s a quick guide to getting started:

1. Install PHPStan: You can install PHPStan via Composer, the PHP dependency manager:

   composer require --dev phpstan/phpstan

1. Configure PHPStan:
   PHPStan can be configured using a phpstan.neon or phpstan.neon.dist file, where you can specify analysis settings, levels, and rules. The configuration file allows for customization to match your project’s needs, including paths to analyze, and ignore rules and extensions.

2. Set an Analysis Level:
   PHPStan offers different analysis levels (from 0 to 8), where 0 is the least strict and 8 is the strictest. It’s often recommended to start with a lower level and gradually increase as your codebase improves.
   

   phpstan analyse --level max src

1. Run PHPStan: To analyze your codebase, simply run:

   phpstan analyse src

PHPStan will output warnings and errors with context on where they’re found in the code, allowing you to address them before proceeding.

1. Integrate with CI/CD: PHPStan can be added to your CI/CD pipeline to ensure code quality checks are automated. Many CI services, like GitHub Actions, GitLab CI, and Travis CI, have options for easily integrating PHPStan.

By making PHPStan a part of your development and review process, you can reduce the likelihood of bugs, improve code quality, and instill more confidence in your PHP code.

---

On Laravel Projects

1: If you’re working on a Laravel project, you can leverage the larastan package, which is tailored for Laravel applications and provides additional features and checks specific to Laravel. To install larastan, run:

composer require --dev "larastan/larastan:^2.0"

2: Then, create a phpstan.neon or phpstan.neon.dist file in the root of your application. It might look like this:

includes:
    - vendor/larastan/larastan/extension.neon

parameters:

    paths:
        - app/

    # Level 9 is the highest level
    level: 5

#    ignoreErrors:
#        - '#PHPDoc tag @var#'
#
#    excludePaths:
#        - ./*/*/FileToBeExcluded.php
#
#    checkMissingIterableValueType: false

For all available options, please take a look at the PHPStan documentation: https://phpstan.org/config-reference

3: Finally, you may start analyzing your code using the phpstan console command:

If you are getting the error Allowed memory size exhausted, then you can use the --memory-limit option fix the problem:

./vendor/bin/phpstan analyse --memory-limit=2G

Ignoring errors

Ignoring a specific error can be done either with a php comment or in the configuration file:

// @phpstan-ignore-next-line
$test->badMethod();

$test->badMethod(); // @phpstan-ignore-line

When ignoring errors in PHPStan's configuration file, they are ignored by writing a regex based on error messages:

parameters:
    ignoreErrors:
        - '#Call to an undefined method .*badMethod\(\)#'

Baseline file
In older codebases it might be hard to spend the time fixing all the code to pass a high PHPStan Level.

To get around this a baseline file can be generated. The baseline file will create a configuration file with all of the current errors, so new code can be written following a higher standard than the old code. (PHPStan Docs)

./vendor/bin/phpstan analyse --generate-baseline

What’s New in PHPStan 2.0?

With PHPStan 2.0, the tool has introduced several powerful new features, enhancing its capabilities and making it even more effective for developers.

1. Enhanced Type Inference: PHPStan 2.0 offers improved type inference, which means it can more accurately understand complex type relationships in your code. This results in better detection of issues and a more reliable analysis.

2. Support for Generics: PHPStan 2.0 has significantly enhanced support for generics in PHP, providing more accurate type-checking for generic code patterns, especially within frameworks and libraries. This update allows for cleaner code with less boilerplate, making it easier to write generic classes and functions.

3. Better Handling of Legacy Code: PHPStan 2.0 has been optimized to analyze legacy codebases more efficiently, helping developers modernize older projects without overwhelming them with errors.

4. Increased Performance: The latest version of PHPStan is faster, allowing it to analyze larger codebases more efficiently, which is particularly beneficial in CI/CD environments where speed is critical.

5. New Rule Customizations: With PHPStan 2.0, developers have more control over which rules and checks are enforced. This is especially useful for teams that have specific coding standards or preferences.

PHPStan 2.0 represents a significant leap forward in static analysis for PHP, offering deeper insight, more flexibility, and better performance to streamline code quality efforts.

---

Tips for Maximizing PHPStan’s Impact

To get the most out of PHPStan, consider these tips:

• Start Slowly: Introduce PHPStan at a lower analysis level and increase gradually as the team becomes more comfortable.
• Use Baseline Files: PHPStan allows you to create a baseline of existing errors to focus on new issues. This is particularly helpful in legacy codebases where fixing all issues at once may not be feasible.
• Invest in Custom Rules: If your project has specific coding standards, consider writing custom rules for PHPStan. This can help reinforce project-specific conventions and maintain consistency.
• Embrace Type Hints: The more type hints you use in your code, the better PHPStan can analyze it. Encourage type hinting for variables, parameters, and return types throughout the project.

---

Conclusion

PHPStan has transformed static analysis for PHP developers, bringing a powerful set of tools to identify and address issues early in the development process. With the release of PHPStan 2.0, it’s more capable than ever, boasting enhanced type inference, better support for generics, and performance improvements that make it a vital tool for modern PHP development.

By integrating PHPStan into your development workflow, you’re investing in code quality, reducing bugs, and ultimately creating a more reliable and maintainable codebase. Whether you’re working on a large, collaborative project or just trying to improve a personal project, PHPStan is a valuable asset that every PHP developer should consider.