[#4] add PHPMock::defineFunctionMock() as a workaround for bug#68541

Author: malkusch

README.md

@@ -62,6 +62,22 @@ class BuiltinTest extends \PHPUnit_Framework_TestCase
 There's no need to disable the mocked function. The PHPUnit integration does
 that for you.
 
+## Restrictions
+
+This library comes with the same restrictions as the underlying
+[`php-mock`](https://github.com/php-mock/php-mock#requirements-and-restrictions):
+
+* Only *unqualified* function calls in a namespace context can be mocked.
+  E.g. a call for `time()` in the namespace `foo` is mockable,
+  a call for `\time()` is not.
+
+* The mock has to be defined before the first call to the unqualified function
+  in the tested class. This is documented in [Bug #68541](https://bugs.php.net/bug.php?id=68541).
+  In most cases you can ignore this restriction. But if you happen to run into
+  this issue you can call [`PHPMock::defineFunctionMock()`](http://php-mock.github.io/php-mock-phpunit/api/class-phpmock.phpunit.PHPMock.html#_defineFunctionMock)
+  before that first call (e.g. with `@beforeClass`).
+  This would define a side effectless namespaced function.
+
 # License and authors
 
 This project is free and under the WTFPL.

classes/PHPMock.php

@@ -108,4 +108,33 @@ public function registerForTearDown(Deactivatable $deactivatable)
         $result = $this->getTestResultObject();
         $result->addListener(new MockDisabler($deactivatable));
     }
+    
+    /**
+     * Defines the mocked function in the given namespace.
+     *
+     * In most cases you don't have to call this method. {@link getFunctionMock()}
+     * is doing this for you. But if the mock is defined after the first call in the
+     * tested class, the tested class doesn't resolve to the mock. This is
+     * documented in Bug #68541. You therefore have to define the namespaced
+     * function before the first call (e.g. with @beforeClass).
+     *
+     * Defining the function has no side effects. If the function was
+     * already defined this method does nothing.
+     *
+     * @see getFunctionMock()
+     * @link https://bugs.php.net/bug.php?id=68541 Bug #68541
+     *
+     * @param string $namespace The function namespace.
+     * @param string $name      The function name.
+     */
+    public function defineFunctionMock($namespace, $name)
+    {
+        $functionMockBuilder = new MockBuilder();
+        $functionMockBuilder->setNamespace($namespace)
+                            ->setName($name)
+                            ->setFunction(function () {
+                            })
+                            ->build()
+                            ->define();
+    }
 }

tests/PHPMockTest.php

@@ -27,6 +27,34 @@ protected function disableMocks()
     {
     }
 
+    /**
+     * Tests defineFunctionMock().
+     *
+     * @test
+     */
+    public function testDefineFunctionMock()
+    {
+        $this->defineFunctionMock(__NAMESPACE__, "escapeshellcmd");
+        self::escapeshellcmd("foo");
+        
+        $mock = $this->getFunctionMock(__NAMESPACE__, "escapeshellcmd");
+        $mock->expects($this->once())->willReturn("bar");
+        
+        $this->assertEquals("bar", self::escapeshellcmd("foo"));
+    }
+    
+    /**
+     * Returns the built-in call to escapeshellcmd().
+     *
+     * @param string $command Shell command.
+     *
+     * @return string The built-in call.
+     */
+    private static function escapeshellcmd($command)
+    {
+        return escapeshellcmd($command);
+    }
+    
     /**
      * Tests building a mock with arguments.
      *