PHP Static Code Analysis: Using Tools like PHPStan

In the world of PHP development, writing clean, efficient, and error-free code is paramount. But how can we ensure our code meets these standards? Enter static code analysis – a powerful technique that examines source code without executing it. Today, we’ll dive deep into PHP static code analysis, with a particular focus on PHPStan, one of the most popular tools in this domain.

Table of Contents

What is Static Code Analysis?

Static code analysis is a method of debugging by examining source code before a program is run. It’s an automated way to check code for potential bugs, stylistic errors, and suspicious constructs. Think of it as a super-powered linter that goes beyond just checking syntax.

🔍 Fun Fact: Static analysis can detect up to 50% of bugs before runtime!

Why Use Static Code Analysis in PHP?

Early Bug Detection: Catch errors before they make it to production.
Code Quality Improvement: Enforce coding standards and best practices.
Security Enhancement: Identify potential security vulnerabilities.
Time-Saving: Automate the process of code review.
Continuous Integration: Integrate with CI/CD pipelines for consistent code quality.

Introducing PHPStan

PHPStan (PHP Static Analysis Tool) is an open-source PHP static analysis tool that finds bugs in your code without actually running it. It’s known for its depth of analysis and its ability to understand modern PHP code.

Installing PHPStan

To get started with PHPStan, you’ll need Composer. Run the following command:

composer require --dev phpstan/phpstan

Using PHPStan: A Practical Example

Let’s dive into a practical example to see PHPStan in action. We’ll create a simple PHP class with some intentional issues and then use PHPStan to analyze it.

Create a file named User.php with the following content:

<?php

class User
{
    private string $name;
    private int $age;

    public function __construct(string $name, int $age)
    {
        $this->name = $name;
        $this->age = $age;
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function getAge(): int
    {
        return $this->age;
    }

    public function isAdult(): bool
    {
        return $this->age >= 18;
    }

    public function greet($greeting)
    {
        return $greeting . ', ' . $this->name . '!';
    }
}

$user = new User('John', '30');
echo $user->getName();
echo $user->getUndefinedMethod();

Now, let’s run PHPStan on this file:

vendor/bin/phpstan analyse User.php

PHPStan will output something like this:

 ------ -------------------------------------------------------- 
  Line   User.php                                                
 ------ -------------------------------------------------------- 
  26     Parameter #2 $age of class User constructor expects     
         int, string given.                                      
  28     Call to an undefined method User::getUndefinedMethod(). 
 ------ -------------------------------------------------------- 


 [ERROR] Found 2 errors

Let’s break down what PHPStan found:

On line 26, we’re passing a string ’30’ to the constructor, which expects an integer.
On line 28, we’re calling an undefined method getUndefinedMethod().

These are exactly the kind of issues that static analysis excels at finding – type mismatches and calls to non-existent methods.

Configuring PHPStan

PHPStan can be configured to suit your project’s needs. Create a file named phpstan.neon in your project root:

parameters:
    level: 5
    paths:
        - src
    excludePaths:
        - tests
    checkMissingIterableValueType: false

This configuration:

Sets the analysis level to 5 (out of 9, with 9 being the strictest)
Analyzes files in the src directory
Excludes the tests directory
Disables checks for missing iterable value types

Advanced PHPStan Features

Custom Rule Creation

PHPStan allows you to create custom rules. Let’s create a rule that flags any method named “dangerousOperation”:

<?php

namespace MyApp\PHPStan;

use PhpParser\Node;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;

class NoDangerousOperationRule implements Rule
{
    public function getNodeType(): string
    {
        return Node\Stmt\ClassMethod::class;
    }

    public function processNode(Node $node, Scope $scope): array
    {
        if ($node->name->name === 'dangerousOperation') {
            return [
                "Method named 'dangerousOperation' found. This is potentially unsafe."
            ];
        }

        return [];
    }
}

Add this rule to your phpstan.neon:

services:
    -
        class: MyApp\PHPStan\NoDangerousOperationRule
        tags:
            - phpstan.rules.rule

Baseline Generation

PHPStan can generate a baseline of current errors, allowing you to focus on new issues:

vendor/bin/phpstan analyse --generate-baseline

This creates a phpstan-baseline.neon file. Add it to your configuration:

includes:
    - phpstan-baseline.neon

Integrating PHPStan with CI/CD

To ensure consistent code quality, integrate PHPStan into your CI/CD pipeline. Here’s an example using GitHub Actions:

name: PHP Static Analysis

on: [push, pull_request]

jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: composer install
      - name: Run PHPStan
        run: vendor/bin/phpstan analyse src tests

This workflow runs PHPStan on every push and pull request, ensuring code quality is maintained throughout development.

Best Practices for Using PHPStan

Start Low, Aim High: Begin with a lower level and gradually increase as your codebase improves.
Integrate Early: Add PHPStan to your project as early as possible to catch issues from the start.
Use Type Hints: PHPStan works best with fully typed code. Use PHP 7.4+ type hints extensively.
Custom Configurations: Tailor PHPStan’s configuration to your project’s specific needs.
Regular Updates: Keep PHPStan and its dependencies up to date for the latest features and bug fixes.

🚀 Pro Tip: Use PHPStan’s incremental cache to speed up subsequent runs:

vendor/bin/phpstan analyse --configuration phpstan.neon --memory-limit 1G

Comparing PHPStan with Other Tools

While PHPStan is excellent, it’s not the only static analysis tool for PHP. Let’s compare it with some alternatives:

Tool	Strengths	Weaknesses
PHPStan	Deep analysis, extensible	Steeper learning curve
Psalm	Great for large codebases, security focus	Can be overzealous
PHP_CodeSniffer	Good for coding standards	Limited type analysis
Phan	Fast, good for large projects	Less actively maintained

Conclusion

Static code analysis, particularly with tools like PHPStan, is an invaluable asset in a PHP developer’s toolkit. It catches errors early, improves code quality, and can even enhance security. By integrating PHPStan into your development workflow, you’re taking a significant step towards more robust, reliable PHP applications.

Remember, static analysis is not a silver bullet – it’s a powerful tool that complements (but doesn’t replace) good coding practices, thorough testing, and careful code reviews. Use it wisely, and watch your PHP code quality soar!

Happy coding, and may your PHP be ever error-free! 🐘✨