Установка

Fedora

На момент написания этой документации актуальной версией этого дистрибутива Linux является Fedora 44. По умолчанию в неё входит PHP 8.5. Вот как установить интерпретатор PHP для командной строки вместе с расширениями, необходимыми для PHPUnit:

sudo dnf install php-cli \
                 php-json \
                 php-mbstring \
                 php-process \
                 php-xml \
                 php-pecl-pcov \
                 php-pecl-xdebug

Если вы используете более старую версию Fedora, ознакомьтесь с репозиторием пакетов, который поддерживает Реми Колле.

Debian

На момент написания этой документации актуальной версией этого дистрибутива Linux является Debian 13. По умолчанию в неё входит PHP 8.4. Вот как установить интерпретатор PHP для командной строки вместе с расширениями, необходимыми для PHPUnit:

sudo apt install php-cli \
                 php-json \
                 php-mbstring \
                 php-xml \
                 php-pcov \
                 php-xdebug

Если вы используете более старую версию Debian, ознакомьтесь с репозиторием пакетов, который поддерживает Ондржей Сури.

Ubuntu

На момент написания этой документации актуальной версией этого дистрибутива Linux является Ubuntu 26.04. По умолчанию в неё входит PHP 8.5. Вот как установить интерпретатор PHP для командной строки вместе с расширениями, необходимыми для PHPUnit:

sudo apt install php-cli \
                 php-json \
                 php-mbstring \
                 php-xml \
                 php-pcov \
                 php-xdebug

Если вы используете более старую версию Ubuntu, ознакомьтесь с репозиторием пакетов, который поддерживает Ондржей Сури.

macOS

Самый распространённый способ установить PHP в macOS — использовать Homebrew. Инструкции ниже предполагают, что Homebrew уже установлен и настроен.

Мы воспользуемся формулами homebrew-php, которые поддерживает Шивам Матур. Следующая команда загрузит эти формулы:

brew tap shivammathur/php
brew tap shivammathur/extensions

Следующая команда установит PHP 8.4:

brew install shivammathur/php/php@8.4

Следующие расширения, необходимые для PHPUnit, уже установлены и включены по умолчанию:

• dom

• json

• libxml

• mbstring

• xml

• xmlwriter

Если вы хотите собирать данные о покрытии кода, необходимо дополнительно установить и включить одно из следующих расширений:

• pcov

• xdebug

Следующая команда установит и включит расширение pcov:

brew install pcov@8.4

Следующая команда установит и включит расширение xdebug:

brew install xdebug@8.4

Windows

Ручная загрузка PHAR

Вы можете просто скачать выпуск PHPUnit, упакованный в PHP-архив, и сразу же использовать его:

wget -O phpunit.phar https://phar.phpunit.de/phpunit-10.phar

php phpunit.phar --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.

Обычно PHAR делают исполняемым:

chmod +x phpunit.phar

Теперь вы можете непосредственно запустить PHAR:

./phpunit.phar --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.

Все официальные выпуски, распространяемые проектом PHPUnit, подписаны менеджером соответствующего выпуска. PGP-подписи и хеши SHA256 для проверки доступны на https://phar.phpunit.de/.

Вот пример ручной проверки PHP-архива выпуска PHPUnit с помощью его PGP-подписи:

wget -O phpunit.phar https://phar.phpunit.de/phpunit-10.phar
wget -O phpunit.phar.asc https://phar.phpunit.de/phpunit-10.phar.asc
gpg --keyserver pgp.uni-mainz.de --recv-keys 0x4AA394086372C20A
gpg phpunit.phar.asc

Обычно в разных проектах используют разные версии PHPUnit. Для этого PHP-архив PHPUnit помещают в каталог проекта. Типичная структура каталогов PHP-проекта выглядит так:

├── public
├── src
├── tests
└── tools

Каталог public содержит статические ресурсы приложения (CSS, JavaScript, изображения и т. д.); это корневой каталог документов веб-сервера.

Каталог src содержит исходный код PHP приложения. Каталог tests содержит набор тестов приложения.

Каталог tools содержит инструменты, например PHPUnit, упакованные в PHP-архивы.

Разумеется, вы можете вручную скачать PHP-архив PHPUnit в каталог tools:

wget -O phpunit.phar https://phar.phpunit.de/phpunit-10.phar
chmod +x phpunit.phar
mv phpunit.phar tools

Установка PHPUnit с помощью Phive

Для управления инструментами PHP-проекта, распространяемыми в виде PHAR, можно использовать Phive — среду установки и проверки PHAR.

Вот как установить Phive:

wget https://phar.io/releases/phive.phar
wget https://phar.io/releases/phive.phar.asc
gpg --keyserver hkps.pool.sks-keyservers.net --recv-keys 0x9B2D5D79
gpg --verify phive.phar.asc phive.phar
chmod +x phive.phar
mv phive.phar /usr/local/bin/phive

После установки Phive PHPUnit можно установить следующим образом:

phive install phpunit

После выполнения приведённой выше команды каталог проекта будет выглядеть так:

├── .phive
|   └── phars.xml
├── public
├── src
├── tests
└── tools
    └── phpunit -> ~/.phive/phars/phpunit-10.0.0.phar

Phive скачал PHP-архив PHPUnit 10.0.0, поместил его в кэш в домашнем каталоге и создал оттуда символическую ссылку на tools/phpunit.

Теперь можно запустить локальную установку PHPUnit для проекта, выполнив ./tools/phpunit:

./tools/phpunit --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.

Файл .phive/phars.xml, созданный в корневом каталоге проекта, содержит метаданные о зависимостях инструментов проекта:

<?xml version="1.0" encoding="UTF-8"?>
<phivexmlns="https://phar.io/phive">
<pharname="phpunit"
version="^10.0"installed="10.0.0"
location="./tools/phpunit"copy="true"/>
</phive>

Файл .phive/phars.xml следует добавить в систему контроля версий.

^10.0 — это ограничение семантического версионирования: Phive всегда будет устанавливать последнюю версию PHPUnit, совместимую с PHPUnit 10.0.

Phive не только предоставляет удобный способ установки, управления и обновления инструментов, распространяемых в виде PHP-архивов. Phive также обеспечивает безопасность, автоматически проверяя PGP-подписи при скачивании файлов PHAR.

Если вы хотите хранить PHP-архив PHPUnit в системе контроля версий, используйте параметр --copy Phive, чтобы скопировать PHP-архив из кэша в домашнем каталоге в каталог инструментов проекта:

phive install --copy phpunit

После выполнения приведённой выше команды каталог проекта будет выглядеть так:

├── .phive
|   └── phars.xml
├── public
├── src
├── tests
└── tools
    └── phpunit

Обновление PHPUnit с помощью Phive

phive install phpunit добавляет зависимость от PHPUnit с ограничением версии, в котором для семантического версионирования используется оператор каретки (^): version="^10.0".

При такой конфигурации Phive всегда будет устанавливать последнюю версию PHPUnit, совместимую с PHPUnit 10.0.

Это позволяет вам «оставаться в курсе» обновлений, пока PHPUnit 10 остаётся текущей стабильной версией PHPUnit, включая новые минорные версии, такие как PHPUnit 10.1. Когда выйдет PHPUnit 11, Phive не установит его автоматически и неожиданно.

<?xml version="1.0" encoding="UTF-8"?>
<phivexmlns="https://phar.io/phive">
<pharname="phpunit"
version="^9.6"installed="9.6.0"
location="./tools/phpunit"copy="true"/>
</phive>

phive outdated
Phive 0.15.2 - Copyright (C) 2015-2023 by Arne Blankerts, Sebastian Heuer and Contributors
Found 1 outdated PHARs in phive.xml:

Name       Version Constraint    Installed    Available

phpunit    ^9.6                  9.6.0        9.6.3

<?xml version="1.0" encoding="UTF-8"?>
<phivexmlns="https://phar.io/phive">
<pharname="phpunit"
version="^9.6"installed="9.6.3"
location="./tools/phpunit"copy="true"/>
</phive>

phive outdated
Phive 0.15.2 - Copyright (C) 2015-2023 by Arne Blankerts, Sebastian Heuer and Contributors
Congrats, no outdated phars found

phive install phpunit@^10.0
Phive 0.15.2 - Copyright (C) 2015-2024 by Arne Blankerts, Sebastian Heuer and Contributors
Linking /home/sb/.phive/phars/phpunit-10.5.15.phar to /path/to/tools/phpunit

Что находится внутри PHAR?

Чтобы избежать проблем, возникающих, когда тестируемый код использует общие с PHPUnit зависимости, но требует версии, отличающиеся от включённых в PHAR, был принят ряд мер.

Например, большинство модулей кода, включённых в дистрибутив PHPUnit в формате PHAR, в том числе все зависимости, такие как каталоги vendor, перемещаются в новое отдельное пространство имён. Это не относится к классам, входящим в публичный API PHPUnit, например PHPUnit\Framework\TestCase.

PHAR PHPUnit не использует динамическую автозагрузку для загрузки входящих в него модулей кода. Вместо этого все модули кода, включённые в PHAR, загружаются при запуске.

Подробнее об этих мерах рассказывается в этой статье.

Иногда необходимо точно знать, какие версии зависимостей PHPUnit включены в дистрибутив PHPUnit в формате PHAR, например, в контексте безопасности цепочки поставок программного обеспечения. Для этого в дистрибутиве PHPUnit в формате PHAR предусмотрены дополнительные параметры CLI, которых нет у средства запуска тестов, установленного через Composer.

Если запустить PHAR PHPUnit с параметром CLI --manifest, будет выведен текстовый манифест с информацией о версиях зависимостей PHPUnit, включённых в PHAR:

php phpunit-10.5.1.phar --manifest
phpunit/phpunit: 10.5.1
myclabs/deep-copy: 1.11.1
nikic/php-parser: v4.17.1
phar-io/manifest: 2.0.3
phar-io/version: 3.2.1
phpunit/php-code-coverage: 10.1.9
phpunit/php-file-iterator: 4.1.0
phpunit/php-invoker: 4.0.0
phpunit/php-text-template: 3.0.1
phpunit/php-timer: 6.0.0
sebastian/cli-parser: 2.0.0
sebastian/code-unit: 2.0.0
sebastian/code-unit-reverse-lookup: 3.0.0
sebastian/comparator: 5.0.1
sebastian/complexity: 3.1.0
sebastian/diff: 5.0.3
sebastian/environment: 6.0.1
sebastian/exporter: 5.1.1
sebastian/global-state: 6.0.1
sebastian/lines-of-code: 2.0.1
sebastian/object-enumerator: 5.0.0
sebastian/object-reflector: 3.0.0
sebastian/recursion-context: 5.0.0
sebastian/type: 4.0.0
sebastian/version: 4.0.1
theseer/tokenizer: 1.2.2

Если запустить PHAR PHPUnit с параметром CLI --sbom, будет выведена ведомость программного обеспечения (SBOM) в формате XML с информацией о версиях зависимостей PHPUnit, включённых в PHAR:

php phpunit-10.5.1.phar --sbom
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.4">
 <components>
  <component type="library">
   <group>phpunit</group>
   <name>phpunit</name>
   <version>10.5.1</version>
   <description>The PHP Unit Testing framework.</description>
   <licenses>
    <license>
     <id>BSD-3-Clause</id>
    </license>
   </licenses>
   <purl>pkg:composer/phpunit/phpunit@10.5.1</purl>
  </component>
  .
  .
  .

Если запустить PHAR PHPUnit с параметром CLI --composer-lock, будет выведен файл composer.lock, использованный для установки зависимостей PHPUnit при сборке PHAR:

php phpunit-10.5.1.phar --composer-lock
{
    "_readme": [
        "This file locks the dependencies of your project to a known state",
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
        "This file is @generated automatically"
    ],
    "content-hash": "e06728e5442edec84af96f94a889b4a7",
    .
    .
    .

Установка PHPUnit с помощью Composer

Приведённая ниже команда предполагает, что вы уже установили Composer, а его исполняемый файл composer доступен в пути поиска $PATH. Установка Composer описана на сайте этого инструмента.

composer require --dev phpunit/phpunit

После выполнения приведённой выше команды каталог проекта будет выглядеть так:

├── composer.json
├── composer.lock
├── public
├── src
├── tests
└── vendor

Например, файл composer.json содержит метаданные о зависимостях вашего проекта. Этот файл необходимо добавить в систему контроля версий.

Файл composer.lock содержит список точных версий зависимостей, установленных Composer. Хотя технически этот файл необязателен, рекомендуется добавить его в систему контроля версий.

Локальную установку PHPUnit для проекта можно запустить так:

./vendor/bin/phpunit --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.

Обновление PHPUnit с помощью Composer

composer require --dev phpunit/phpunit добавляет зависимость для разработки от PHPUnit с ограничением версии, в котором для семантического версионирования используется оператор каретки (^): "phpunit/phpunit": "^10.0".

При такой конфигурации Composer всегда будет устанавливать последнюю версию PHPUnit, совместимую с PHPUnit 10.0.

Это позволяет вам «оставаться в курсе» обновлений, пока PHPUnit 10 остаётся текущей стабильной версией PHPUnit, включая новые минорные версии, такие как PHPUnit 10.1. Когда выйдет PHPUnit 11, Composer не установит его автоматически и неожиданно.

{
"require-dev":{
"phpunit/phpunit":"^9.6"
}
}

composer outdated --minor-only
Legend:
! patch or minor release available - update recommended
~ major release available - update possible

Direct dependencies required in composer.json:
phpunit/phpunit 9.6.0 ! 9.6.3 The PHP Unit Testing framework.

{
"require-dev":{
"phpunit/phpunit":"^9.6"
}
}

composer outdated
Legend:
! patch or minor release available - update recommended
~ major release available - update possible

Direct dependencies required in composer.json:
phpunit/phpunit                    9.6.3  ~ 10.0.7 The PHP Unit Testing framework.

{
"require-dev":{
"phpunit/phpunit":"^10.0"
}
}