zalas/phpunit-globals

Allows to use annotations to define global variables in PHPUnit test cases.

PHPUnit Globals

Allows to use attributes to define global variables in PHPUnit test cases., _(*1)

, _(*2)

Supported attributes: * #[Env] for $_ENV * #[Server] for $_SERVER * #[Putenv] for putenv(), _(*3)

Annotations were previously supported up until v3.5.0 (inclusive). Annotation support is complete, so if you plan on using them keep using v3.5 of this package., _(*4)

Global variables are set before each test case is executed, and brought to the original state after each test case has finished. The same applies to putenv()/getenv() calls., _(*5)

Installation

Composer

composer require --dev zalas/phpunit-globals

Phar

The extension is also distributed as a PHAR, which can be downloaded from the most recent Github Release., _(*6)

Put the extension in your PHPUnit extensions directory. Remember to instruct PHPUnit to load extensions in your phpunit.xml using the extensionsDirectory attribute:, _(*7)

<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="file://./vendor/phpunit/phpunit/phpunit.xsd"
         extensionsDirectory="tools/phpunit.d"
>
</phpunit>

Usage

Enable the globals attribute extension in your PHPUnit configuration:, _(*8)

<phpunit ...>

    <!-- ... -->

    <extensions>
        <bootstrap class="Zalas\PHPUnit\Globals\AttributeExtension" />
    </extensions>
</phpunit>

Make sure the AttributeExtension is registered before any other extensions that might depend on global variables., _(*9)

Global variables can now be defined in attributes:, _(*10)

use PHPUnit\Framework\TestCase;
use Zalas\PHPUnit\Globals\Attribute\Env;
use Zalas\PHPUnit\Globals\Attribute\Server;
use Zalas\PHPUnit\Globals\Attribute\Putenv;

#[Env('FOO', 'bar')]
class ExampleTest extends TestCase
{
    #[Env('APP_ENV', 'foo')]
    #[Env('APP_DEBUG', '0')]
    #[Server('APP_ENV', 'bar')]
    #[Server('APP_DEBUG', '1')]
    #[Putenv('APP_HOST', 'localhost')]
    public function test_global_variables()
    {
        $this->assertSame('bar', $_ENV['FOO']);
        $this->assertSame('foo', $_ENV['APP_ENV']);
        $this->assertSame('0', $_ENV['APP_DEBUG']);
        $this->assertSame('bar', $_SERVER['APP_ENV']);
        $this->assertSame('1', $_SERVER['APP_DEBUG']);
        $this->assertSame('localhost', \getenv('APP_HOST'));
    }
}

It's also possible to mark an attribute with unset so it will not be present in any of the global variables:, _(*11)

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    #[Env('APP_ENV', unset: true)]
    #[Server('APP_DEBUG', unset: true)]
    #[Putenv('APP_HOST', unset: true)]
    public function test_global_variables()
    {
        $this->assertArrayNotHasKey('APP_ENV', $_ENV);
        $this->assertArrayNotHasKey('APP_DEBUG', $_SERVER);
        $this->assertArrayNotHasKey('APP_HOST', \getenv());
    }
}

Updating to PHPUnit 10

When updating from a previous version of this extension dedicated to work with PHPUnit 9, replace the extension registration in phpunit.xml:, _(*12)

    <extensions>
        <extension class="Zalas\PHPUnit\Globals\AttributeExtension" />
    </extensions>

with:, _(*13)

    <extensions>
        <bootstrap class="Zalas\PHPUnit\Globals\AttributeExtension" />
    </extensions>

Contributing

Please read the Contributing guide to learn about contributing to this project. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms., _(*14)