Skip to content

Commit

Permalink
Document how to integrate with PHPUnit
Browse files Browse the repository at this point in the history
Right now, it is possible to display Doctrine deprecations with a bit of
PHPUnit configuration.
Note that this does not seem to clash with triggering self-deprecations,
provided you use the VerifyDeprecations trait in tests that call the
deprecated pieces of code.
  • Loading branch information
greg0ire committed Dec 1, 2024
1 parent 0d0c25d commit a8a2989
Show file tree
Hide file tree
Showing 3 changed files with 86 additions and 3 deletions.
61 changes: 61 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,67 @@ class MyTest extends TestCase
}
```

## Displaying deprecations after running a PHPUnit test suite

It is possible to integrate this library with PHPUnit to display all
deprecations triggered during the test suite execution.

```xml
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
colors="true"
bootstrap="vendor/autoload.php"
displayDetailsOnTestsThatTriggerDeprecations="true"
failOnDeprecation="true"
>
<!-- one attribute to display the deprecations, the other to fail the test suite -->

<php>
<!-- ensures native PHP deprecations are used -->
<server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
</php>

<!-- ensures the @ operator in @trigger_error is ignored -->
<source ignoreSuppressionOfDeprecations="true">
<include>
<directory>src</directory>
</include>
</source>
</phpunit>
```

Note that you can still trigger Deprecations in your code, provided you use the
`#[WithoutErrorHandler]` attribute to disable PHPUnit's error handler for tests
that call it. Be wary that this will disable all error handling, meaning it
will mask any warnings or errors that would otherwise be caught by PHPUnit.

At the moment, it is not possible to disable deduplication with an environment
variable, but you can use a bootstrap file to achieve that:

```php
// tests/bootstrap.php
<?php

declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';

use Doctrine\Deprecations\Deprecation;

Deprecation::withoutDeduplication();
```

Then, reference that file in your PHPUnit configuration:

```xml
<phpunit
bootstrap="tests/bootstrap.php"
>
</phpunit>
```

## What is a deprecation identifier?

An identifier for deprecations is just a link to any resource, most often a
Expand Down
6 changes: 3 additions & 3 deletions src/Deprecation.php
Original file line number Diff line number Diff line change
Expand Up @@ -226,19 +226,19 @@ private static function basename(string $filename): string

public static function enableTrackingDeprecations(): void
{
self::$type = self::$type ?? 0;
self::$type = self::$type ?? self::getTypeFromEnv();
self::$type |= self::TYPE_TRACK_DEPRECATIONS;
}

public static function enableWithTriggerError(): void
{
self::$type = self::$type ?? 0;
self::$type = self::$type ?? self::getTypeFromEnv();
self::$type |= self::TYPE_TRIGGER_ERROR;
}

public static function enableWithPsrLogger(LoggerInterface $logger): void
{
self::$type = self::$type ?? 0;
self::$type = self::$type ?? self::getTypeFromEnv();
self::$type |= self::TYPE_PSR_LOGGER;
self::$logger = $logger;
}
Expand Down
22 changes: 22 additions & 0 deletions tests/EnvTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?php

declare(strict_types=1);

namespace Doctrine\Deprecations;

use PHPUnit\Framework\TestCase;
use ReflectionProperty;

class EnvTest extends TestCase
{
public function testEnvIsTakenIntoAccountWhenCallingEnableTrackingDeprecations(): void
{
$_ENV['DOCTRINE_DEPRECATIONS'] = 'trigger';
Deprecation::enableTrackingDeprecations();
$reflectionProperty = new ReflectionProperty(Deprecation::class, 'type');
$reflectionProperty->setAccessible(true);
self::assertSame(1 | 2, $reflectionProperty->getValue());
unset($_ENV['DOCTRINE_DEPRECATIONS']);
$reflectionProperty->setValue(null, null);
}
}

0 comments on commit a8a2989

Please sign in to comment.