phpunit.xml vs phpunit.xml.dist

As a PHP programmer I’ve seen projects with a phpunit.xml file or a phpunit.xml.dist file (or even both, which is a mistake). These are configuration files for PHPUnit but why the two different file names?

Which does PHPUnit use?

PHPUnit first tries to use phpunit.xml and if that file does not exist, then it tries to use phpunit.xml.dist instead. PHPUnit only uses one of these files, never both.

From the PHPUnit’s documentation:

If phpunit.xml or phpunit.xml.dist (in that order) exist in the current working directory and –configuration is not used, the configuration will be automatically read from that file.

Best Practices

1. Include phpunit.xml.dist in your Git repository
2. Add phpunit.xml to your .gitignore file

PHPUnit will use phpunit.xml.dist but if a person wants to run a modified set of the tests, they can copy your phpunit.xml.dist file into phpunit.xml and then modify phpunit.xml without introducing changes to the repo.

Other Resources

See the answer from Sebastian Bergmann, author of PHPUnit, on this topic in this stack overflow thread Is there any difference in naming the PHPunit configuration file phpunit.xml.dist or phpunit.xml

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.