Gecko Php Unit Laravel Package

Getting Started

The package is a grab-bag of PHPUnit add-ons from the PHPUnit 5/6 era: an Assertions trait of static-style helpers, a set of custom Constraint classes (string, file, JSON/XML), a MockBuilder wrapper, and a test listener that shortens failure stack traces. Treat it as a supplement to PHPUnit, not a framework.

Install as a dev dependency, pinned to a release whose composer.json matches your PHPUnit major:

composer require --dev gecko-packages/gecko-php-unit

If Composer refuses to resolve, that is the package telling you your PHPUnit is too new — see Gotchas.

Where to look first

1. src/Assertions.php — the trait; this is 80% of the day-to-day value. Skim the method list and map it onto what your PHPUnit version is missing.
2. src/Constraints/ — one small class per constraint; read evaluate() to understand exactly what is compared.
3. src/Extensions/ — the listener(s); check the exact FQCN here before wiring phpunit.xml, the namespace is plural here but singular elsewhere.
4. tests/ — the package's own suite is the de facto documentation; there is no manual.

First use case

Pull the trait into your base test case and replace hand-rolled string/file assertions:

use PHPUnit\Framework\TestCase;
use GeckoPackages\PHPUnit\Assertions;

class ReceiptTest extends TestCase
{
    use Assertions;

    public function testReceiptIsEmitted(): void
    {
        $json = $this->generateReceipt();

        $this->assertStringContains('EUR', $json);
        $this->assertJsonStringEqualsJsonFile(__DIR__.'/fixtures/receipt.json', $json);
    }
}

Second step: register the trace-shortening listener so failures point at your test, not at fifteen frames of PHPUnit internals.

Implementation Patterns

Trait on a shared base class. Don't use Assertions in every test — put it on tests/TestCase.php alongside your app helpers, so constraint availability is uniform and a future migration to native assertions is a one-file change.

Constraints via assertThat when you need composition. The trait methods are thin wrappers; drop to the constraint object when you want to negate, chain, or reuse:

use GeckoPackages\PHPUnit\Constraints\StringContains;

$this->assertThat($logLine, new StringContains('payment captured'));
$this->assertThat($logLine, $this->logicalNot(new StringContains('payment failed')));

Custom constraint from a template. When the built-ins don't cover a domain rule, copy the nearest constraint in src/Constraints/ rather than writing a PHPUnit\Framework\Constraint\Constraint from scratch — the package base class carries the failure-description and exporter conventions that make diffs readable:

class IsValidIban extends \GeckoPackages\PHPUnit\Constraints\Constraint
{
    protected function matches($other): bool { return Iban::validate($other); }
    public function toString(): string { return 'is a valid IBAN'; }
}

Listener registration. In phpunit.xml:

<phpunit>
    <listeners>
        <listener class="GeckoPackages\PHPUnit\Extensions\ShortenedTraceExtension"/>
    </listeners>
</phpunit>

Verify the class name against src/Extensions/ — a typo here fails silently as "class not found" only when a test errors, which is easy to miss on a green build.

Data providers plus constraints. Constraints pair well with providers for file/fixture matrices: iterate fixture paths, assertThat($path, new FileExists()) up front, then assert content. This gives one clear failure ("fixture missing") instead of a confusing content mismatch.

MockBuilder wrapper. If you use it, confine it to a helper such as createMockFor(string $class, array $methods) so your tests don't hard-code the package's builder API. That single seam is what makes the eventual removal cheap.

CI integration tip. Add a composer why gecko-packages/gecko-php-unit line to your upgrade checklist; when PHPUnit is bumped, this dependency is the first thing that breaks resolution and you want it visible in review, not in a red pipeline.

Gotchas and Tips

It is abandoned — plan for removal, not adoption. Last release February 2018. There will be no PHP 8 compatibility fixes, no PHPUnit 9/10/11 support, and no response to issues. The only defensible reason to add it today is a legacy suite already pinned to PHPUnit 5/6; for anything new, the cost/benefit is negative.

Composer will hard-fail on modern PHPUnit. The phpunit/phpunit constraint in its composer.json is ~4|~5 (check the tag you pin), so composer require --dev phpunit/phpunit ^10 alongside it produces an unsatisfiable set. Workarounds people reach for — --ignore-platform-reqs, replace blocks, forking the constraint — all leave you with a listener that implements the removed TestListener interface, which PHPUnit 10+ cannot load at all.

Most of its value is now native. Before rewriting anything, check the modern equivalents: assertStringContainsString, assertStringStartsWith, assertStringEndsWith, assertMatchesRegularExpression, assertJsonStringEqualsJsonString, assertJsonStringEqualsJsonFile, assertFileExists, assertDirectoryExists, assertStringEqualsFile. Nearly every trait method has a first-class PHPUnit counterpart since 7.5/8. Migration is usually mechanical find-and-replace, and it deletes a dependency.

Assertion argument order flips. The trait's helpers are expected, actual (matching PHPUnit convention), but people migrating from string functions write str_contains($haystack, $needle) order out of muscle memory. A silently swapped pair still passes on symmetric cases and produces a baffling diff otherwise. When in doubt, read the trait method signature in src/Assertions.php.

Namespace inconsistency is real. GeckoPackages\PHPUnit\Extensions (listener) versus GeckoPackages\PHPUnit\Extension in older tags, and Constraints vs Constraint for the base class. Copy FQCNs from the source tree, never from a blog post — most published snippets target different tags.

Failure output differs from native assertions. Constraint failures render through the package's exporter, so --debug and IDE diff viewers see a different string shape than assertSame output. If your team has tooling parsing PHPUnit output, expect noise.

Debugging a constraint. Call ->evaluate($actual, '', true) to get the boolean without throwing, and ->toString() to see the expectation text. Faster than bisecting a failing suite.

Extension points worth keeping if you fork. The Constraint base class and the trace-shortening listener survive a port to modern PHPUnit with modest effort (listener becomes a TestHook/Extension or, more simply, a custom TestRunner event subscriber). The assertion trait does not — delete it in favour of native assertions.

Autoload scope. It belongs in require-dev only; a use Assertions trait accidentally referenced from application code will fatal in production where dev dependencies aren't installed.