Mocks, stubs, and spies for PHP.

I've simplified my testcase to this:

<?php

namespace Tests\Unit;

use Eloquent\Phony\Phpunit\Phony;

class Consumer
{
    public function consume()
    {
    }
}

class Provider
{
    public function create()
    {
        yield;
    }
}

class PhonyTest extends \PHPUnit_Framework_TestCase
{
    public function testPhony()
    {
        $consumer = Phony::mock(Consumer::class);
        $provider = Phony::mock(Provider::class);
        $provider->create->generates();
        $consumer->get()->consume($provider->get()->create());
        self::assertSame(
            $provider->create->firstCall()->returnValue(),
            $consumer->consume->firstCall()->argument(0)
        );
    }
}

The test above fails with unexpected error:

Failed asserting that two variables reference the same object.

I've tested that both arguments of the assert are indeed Generators. Just not the same generator which is a bug.

For confirmation I replaced the line $provider->create->generates(); with $provider->create->returns(new \DateTime); - the test passes with that change.

• [x] Throwable interface / engine error exceptions
• [x] Scalar type hints
• [x] Return type declarations
• [x] Anonymous classes
• [x] Closure::call()
• [x] Expectations
• [x] Generator return expressions

Hey, if you're here about PHP 8 support, please leave a 🚀.

I haven't had a lot of time to work on Phony lately, so PHP 8 support is not available yet. Sorry about that. I'm working on PHP 8 support over on the php-8 branch. The first step is to get the existing feature set running under PHP 8, then release a new version ASAP. After that, I'll look into new features to compliment the new stuff in PHP 8.

Due to the complex nature of this project, I don't really expect any PRs to help out too much, but if you're really keen to contribute, by all means please do.

Thanks for your patience 🙏

HHVM does not support the nullable type outside of Hack code.

Broken by 6bf897cb2215ff209ba5e2794c55faaa63d6b4b4

Fixes #203 Refs thephpleague/oauth2-client#584

Currently my biggest issue with Phony is that after

$handle = Phony::mock(MyClass::class);
$handle->method->returns('whatever');
$mock = $handle->get();

PHPStorm and tools like phpstan do not know that $mock instanceof MyClass. Of course I can add @var annotation for PHPStorm and add an ignored error to phpstan but I don't like that. And I don't like having so many variables in the code either.

Recently I was thinking about some API like this.

$mock = Helpers::createPhonyMock(
    MyClass::class,
    function (InstanceHandle $handle) {
        $handle->method->returns('whatever');
    }
);

It is limiting though because InstanceHandle is not easily available outside of the callback and writing the callback is a pain.

The point of such API is that Helpers::createPhonyMock() always returns an instance of the class that is passed in the first argument. Unlike the first example, this is actually possible to handle in both PHPStorm and phpstan using DynamicReturnTypePlugin and dynamic return type extensions.

Today I found out there is a method Phony::on() which can return InstanceHandle for existing mock. With this method it might be better to use API like this.

$mock = Helpers::createPhonyMock(MyClass::class);
Phony::on($mock)->method->returns('whatever');

It removes the downsides of the second approach while preserving the option of using the dynamic return type tools linked above.

1. Do you think something like $mock = Phony::createMock($class); should be added to Phony directly?
2. Do you have some other hidden trick that you use to solve this?

Can I get some input on what would be the best options for default "empty" values for some built-in types? These currently drive Default values for return types, but in future may also drive some auto-wiring of type-hinted function parameters.

Here's what Phony currently handles:

| Type | Value | | --- | --- | | (none) | null | | bool | false | | int | 0 | | float | .0 | | string | '' | | array | [] | | stdClass | (object) [] | | callable | function () {} | | Traversable | new EmptyIterator() | | Iterator | new EmptyIterator() | | Generator | (function () {return; yield;})() | | <type> | mock(<type>)->mock() |

I'm thinking that the EmptyIterator ones are a strange outlier here, in that you can't wrap them in a mock handle and verify their interactions. Perhaps they should be partial mocks? There's also a few in-built classes not catered for.

Here's some changes I'm considering:

| Type | Value | | --- | --- | | Traversable | partialMock('EmptyIterator')->mock() | | Iterator | partialMock('EmptyIterator')->mock() | | Exception | partialMock('Exception')->mock() | | RuntimeException etc. | partialMock('RuntimeException')->mock() | | Error | partialMock('Error')->mock() | | AssertionError etc. | partialMock('AssertionError')->mock() | | callable | spy() | | Closure | function () {} |

@jmalloc @koden-km @darianbr @parkertr I'm wondering what you guys think of these exporter format changes I'm thinking of making, and whether you have any other suggestions.

I've got a feature in the works to add support for limiting output by breadth. Meaning that if an array or object has more than a fixed number of members, the output will be truncated. If I were to follow the current syntax, it would look something like this (with a breadth of 2):

[1, 2, 3, 4]; // '#0[1, 2, :2]'
(object) ['a' => 'a', 'b' => 'b', 'c' => 'c', 'd' => 'd']; // '#0{a: "a", b: "b", :2}'

With :2 indicating that there are 2 members that are truncated. This is similar to when depth limiting kicks in, like so (with a depth of 0):

[1, 2, 3, 4]; // '#0[:4]'
(object) ['a' => 'a', 'b' => 'b', 'c' => 'c', 'd' => 'd']; // '#0{:4}'

First question is; if such a feature were implemented, what would you consider a reasonable default for breadth?

Secondly, hindsight is making me question why I chose : as the character for this. What do you think about + instead:

#0[1, 2, +2]
#0[+4]

#0{a: "a", b: "b", +2}
#0{+4}

It seems more intuitive to me. The other obvious option is to use ..., but it's a bit less succinct:

#0[1, 2, ...+2]
#0[...+4]

#0{a: "a", b: "b", ...+2}
#0{...+4}

There's probably a good opportunity to replace usage of isolator with a strategy similar to php-mock. That is, declaring functions in a namespace to exploit PHP's function resolution rules, and to swap out real functions with stubbed and spied implementations.

I'm thinking something like this:

namespace My\Namespace;

function rollDice()
{
    return mt_rand(1, 6);
}

$stub = stub('mt_rand');
$stub->with(1, 6)->returns(6);
$stub->declareAs('My\Namespace\mt_rand');

$result = rollDice();

assert(6 === $result);
$stub->calledWith(1, 6);

In the above example, My\Namespace\mt_rand is declared, but its implementation can later be replaced by any stub that declares itself with the same name. That may take some interesting trickery.

Thoughts @jmalloc, @darianbr, @koden-km, @parkertr?

Based on our discussion the other day, here's some quick and dirty ideas.

Promise Results

Easily configure stubs to reject/resolve with a promise. Can be interleaved with regular returns/throws:

$stub = Phony::stub();

$stub
    ->returns(1)
    ->throws($e1)
    ->resolvesTo(2)
    ->rejectsWith($e2);

The above would be equivalent to:

$stub
    ->returns(1)
    ->throws($1)
    ->returns(React\Promise\resolve(2))
    ->throws(React\Promise\reject($e));

Cancellation

Promises can be cancelled, it would be great to be able to verify that the consumer of the promise did/didn't cancel it:

$stub->cancelled()
$stub->neverCancelled()

Notifications

Promises also support notifications, essentially an event handler for a specific promise. It'd be handy to trigger those BEFORE a resolve/reject, but in the same call to the stub.

Maybe something like:

$stub->notifies($n1, $n2)->resolvesTo(null)

I don't know if that's possible, but in that example notifies wouldn't specify the behavior for a specific call, but rather configures the values to sent to the promise via $deferred->notify() before resolving with null.

After recently upgrading a Symfony 5.2 project to PHP 8, I'm getting the following error message:

NOTICE: PHP message: PHP Fatal error:  Uncaught Error: Undefined constant "Eloquent\Phony\Reflection\STDOUT" in /usr/src/app/vendor/eloquent/phony/src/Reflection/FeatureDetector.php:155
Stack trace:
#0 /usr/src/app/vendor/eloquent/phony/src/Reflection/FeatureDetector.php(98): Eloquent\Phony\Reflection\FeatureDetector->Eloquent\Phony\Reflection\{closure}(Object(Eloquent\Phony\Reflection\FeatureDetector))
#1 /usr/src/app/vendor/eloquent/phony/src/Difference/DifferenceEngine.php(50): Eloquent\Phony\Reflection\FeatureDetector->isSupported('stdout.ansi')
#2 /usr/src/app/vendor/eloquent/phony/src/Difference/DifferenceEngine.php(37): Eloquent\Phony\Difference\DifferenceEngine->setUseColor(NULL)
#3 /usr/src/app/vendor/eloquent/phony/src/Facade/FacadeContainerTrait.php(193): Eloquent\Phony\Difference\DifferenceEngine->__construct(Object(Eloquent\Phony\Reflection\FeatureDetector))
#4 /usr/src/app/vendor/eloquent/phony/src/Facade/FacadeContainer.php(18): Eloquent\Phony\Facade\FacadeContainer->initializeContainer(Object(Eloquent\Phony\Assertion\ExceptionAssertionRecorder))
#5 /usr/src/app/vendor/eloquent/phony/src/initialize.php(10): Eloquent\Phony\Facade\FacadeContainer->__construct()
#6 /usr/src/app/vendor/composer/autoload_real.php(71): require('/usr/src/app/ve...')
#7 /usr/src/app/vendor/composer/autoload_real.php(61): composerRequire34151eb540343bf5a399e451787004d2('a4b31be0740d153...', '/usr/src/app/ve...')
#8 /usr/src/app/vendor/autoload.php(7): ComposerAutoloaderInit34151eb540343bf5a399e451787004d2::getLoader()
#9 /usr/src/app/public/index.php(10): require('/usr/src/app/ve...')
#10 {main}
  thrown in /usr/src/app/vendor/eloquent/phony/src/Reflection/FeatureDetector.php on line 155

One solution could be explicitly checking for the CLI SAPI:

--- a/vendor/eloquent/phony/src/Reflection/FeatureDetector.php
+++ b/vendor/eloquent/phony/src/Reflection/FeatureDetector.php
@@ -152,7 +152,7 @@ class FeatureDetector
                 }
                 // @codeCoverageIgnoreEnd

-                return function_exists('posix_isatty') && @posix_isatty(STDOUT);
+                return function_exists('posix_isatty') && PHP_SAPI === 'cli' && @posix_isatty(STDOUT);
             },
         ];
     }

I expected this to work but it throws Eloquent\Phony\Mock\Exception\FinalClassException:

<?php

final class FinalClass {}

interface SomeInterface
{
    public function someMethod(): FinalClass;
}

$final = new FinalClass;

$handle = mock(SomeInterface::class);

$handle->someMethod->returns($final);

In fact it fails as soon as $handle->someMethod is called. Is it the expected behavior? I assumed it would be ok as I specify the instance to return. What is the workaround for this?

Handles https://github.com/eloquent/phony/issues/255, the never return type and some more issues that showed up as errors when running tests.

There are still some failing tests under PHP 8.1 left to be handled.

I've got a bunch of deprecation notices when mocking exceptions, or classes implementing Countable, IteratorAggregate or ArrayAccess.

Return type of PhonyMock_ConnectionException_89::__wakeup() should either be compatible with Exception::__wakeup(): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_TemplateRenderException_90::__wakeup() should either be compatible with Exception::__wakeup(): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_Exception_93::__wakeup() should either be compatible with Exception::__wakeup(): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_Collection_119::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_Collection_119::getIterator() should either be compatible with IteratorAggregate::getIterator(): Traversable, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_Collection_119::offsetExists($a0) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_Collection_119::offsetGet($a0) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice
Return type of PhonyMock_Collection_119::offsetSet($a0, $a1) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice

I've managed to track the cause to this RFC - https://wiki.php.net/rfc/internal_method_return_types

The return types will be fully in the reflection in PHP 9, but PHP 8.1 only includes them as "tentative return types" and the FunctionSignatureInspector::signature() method can't handle it.

For example the \Exception::__wakeup() $functionString looks like this:

Method [  public method __wakeup ] {

  - Parameters [0] {
  }
  - Tentative return [ void ]
}

The tentative return type is not handled by the FunctionSignatureInspector::RETURN_PATTERN regex, so the code for mock class is generated without return type and the deprecation notice gets triggered.

If I understand the RFC correctly, this will stop being a problem in PHP 9.0 as the reflection will just show it as straight up return type, but PHP 9.0 is still ways ahead.

Given:

abstract class C {
    abstract static function fun(): self;
}

Phony::partialMock(
    [
        C::class,
        [
            'static fun' => function () {
                return new C();
            },
        ]
    ]
);

The following fatal error occurs:

Fatal error: Declaration of PhonyMock_C_8::fun() must be compatible with C::fun(): C in vendor/eloquent/phony/src/Mock/MockFactory.php(91) : eval()'d code on line 5

This makes some sense, as that closure is obviously not returning the self type, however adding the self type doesn't/can't work in this scenario either, as in most cases it would refer to the type of the surrounding class (such as a PHPUnit test suite implementation, for example).

FWIW, this is the error given when naively adding :self to the closure:

Call to undefined method ReflectionFunction::getDeclaringClass()

Which I assume is simply because it's a closure, it does not have a declaring class (ReflectionFunction, not ReflectionMethod).

As a workaround I've implemented this static function by hand-rolling a class in my test suite, but this had a number of undesirable knock-on effects, including preventing verifications using onStatic() from working for this function.

My PHP is pretty rusty at this point so I'm having trouble coming up with any good solutions, but figured I may as well document this issue before I forget the details.

Following on from #250.

Issues to consider:

• Constructor argument names
• Tests for argument name clashes
• Expanding with() et. al. to support named arguments?
• Magic calls added by traits