PHPUnit for PHP: Complete Guide with Examples

What is PHPUnit and why is it needed?

PHPUnit is a framework for unit testing in the PHP language. It is part of the xUnit family and provides developers with tools for automating the verification of individual program components (classes, methods, functions).

Why is PHPUnit needed?

• Early error detection: Tests run after every code change, allowing you to instantly identify regressions.
• Code documentation: Well-written tests serve as living documentation, showing how a particular method should work.
• Fearless refactoring: You can confidently rewrite code, knowing that tests will prevent breaking existing functionality.
• Support for TDD (Test-Driven Development): A methodology where you first write a test, then the minimal code to pass it.
• CI/CD integration: PHPUnit easily integrates into continuous integration pipelines (GitHub Actions, GitLab CI, Jenkins).

PHPUnit supports mocks (mock objects), fixtures (test data sets), code coverage, and many other advanced features.

Installing PHPUnit

PHPUnit is installed via Composer, the dependency manager for PHP. If you don't have Composer yet, install it from the official website getcomposer.org.

Global installation (recommended for CLI)

composer global require phpunit/phpunit

After that, make sure the global Composer packages directory is added to your PATH. Verify the installation:

phpunit --version

Local installation (inside a project)

composer require --dev phpunit/phpunit

After this, PHPUnit will be available via vendor/bin/phpunit.

Installing a specific version

composer require --dev phpunit/phpunit:^10.0

Important: The PHPUnit version must match the PHP version in your project. For example, PHPUnit 10 requires PHP 8.1 or higher.

Quick start with a code example

Let's create a simple class Calculator.php and write tests for it.

Step 1. Create the class to test

<?php// src/Calculator.php

class Calculator{    public function add(int $a, int $b): int    {        return $a + $b;    }

    public function subtract(int $a, int $b): int    {        return $a - $b;    }

    public function multiply(int $a, int $b): int    {        return $a * $b;    }

    public function divide(int $a, int $b): float    {        if ($b === 0) {            throw new \\InvalidArgumentException("Division by zero");        }        return $a / $b;    }}

Step 2. Create the test class

<?php// tests/CalculatorTest.php

use PHPUnit\\Framework\\TestCase;

class CalculatorTest extends TestCase{    private Calculator $calculator;

    protected function setUp(): void    {        $this->calculator = new Calculator();    }

    public function testAdd(): void    {        $result = $this->calculator->add(2, 3);        $this->assertEquals(5, $result);    }

    public function testSubtract(): void    {        $result = $this->calculator->subtract(10, 4);        $this->assertEquals(6, $result);    }

    public function testMultiply(): void    {        $result = $this->calculator->multiply(3, 4);        $this->assertEquals(12, $result);    }

    public function testDivide(): void    {        $result = $this->calculator->divide(10, 2);        $this->assertEquals(5.0, $result);    }\