Installation

Before you can write and run tests, PHPUnit needs to be added to your project. The standard, recommended way to do this is through Composer, installing it as a dev dependency — a package your project needs only during development and testing, never in production.

Installing PHPUnit with Composer

From the root of your project (the folder containing composer.json), run:

composer require --dev phpunit/phpunit

The --dev flag tells Composer to record PHPUnit under require-dev in composer.json rather than require. That is exactly the concept covered on the Composer track's Dev Dependencies page — worth a read if require-dev is unfamiliar. In short: dev dependencies are installed on your machine and on CI, but skipped when a production build runs composer install --no-dev, since a live server has no business running a test framework.

The vendor/bin/phpunit Executable

Composer's bin mechanism drops a small wrapper script at vendor/bin/phpunit whenever a package (like PHPUnit) declares a command-line tool. This is the file you invoke to run your tests — you will type ./vendor/bin/phpunit (or just vendor\bin\phpunit on Windows) throughout the rest of this track.

Verifying the Installation

Once the install finishes, confirm PHPUnit is in place and check which version you got:

./vendor/bin/phpunit --version

A successful install prints a line similar to PHPUnit 10.5.x by Sebastian Bergmann and contributors. If instead you see a "command not found" or "file not found" error, double-check that composer require --dev phpunit/phpunit completed without errors and that you are running the command from the project root.

Conventional Project Layout

PHPUnit does not force any particular folder structure, but almost every PHP project follows the same convention: application code lives in src/, and its tests live in a parallel tests/ folder, mirroring the same sub-folder structure and class names with a Test suffix.

my-project/
├── composer.json
├── phpunit.xml
├── src/
│   └── Calculator.php
├── tests/
│   └── CalculatorTest.php
└── vendor/
    └── bin/
        └── phpunit

Keeping tests in their own top-level folder makes it easy to point PHPUnit at "everything under tests/" and to exclude that folder entirely from a production deployment.

A Basic phpunit.xml

Rather than typing a test file path every time, most projects add a phpunit.xml configuration file at the project root that tells PHPUnit where to look. A minimal version looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php">
    <testsuites>
        <testsuite name="Unit">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
</phpunit>

With this file in place you can simply run ./vendor/bin/phpunit with no arguments, and it will discover and run every test under the tests/ directory. There is a lot more phpunit.xml can configure (code coverage, environment variables, groups) — a later page in this track covers that in full.