Bring the code into shape

Author: malkusch

README.md

@@ -13,7 +13,41 @@ composer require php-mock/php-mock-prophecy
 
 # Usage
 
-TODO
+Build a new [`PHPProphet`](http://php-mock.github.io/php-mock-prophecy/api/class-phpmock.prophecy.PHPProphet.html)
+and create function prophecies for a given namespace
+with [`PHPProphet::prophesize()`](http://php-mock.github.io/php-mock-prophecy/api/class-phpmock.prophecy.PHPProphet.html#_prophesize):
+
+```php
+<?php
+
+namespace foo;
+
+use phpmock\prophecy\PHPProphet;
+
+$prophet = new PHPProphet();
+
+$prophecy = $prophet->prophesize(__NAMESPACE__);
+$prophecy->time()->willReturn(123);
+$prophecy->reveal();
+
+assert(123 == time());
+$prophet->checkPredictions();
+```
+
+## 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 prophesized.
+  E.g. a call for `time()` in the namespace `foo` is prophesizable,
+  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 [`PHPProphet::define()`](http://php-mock.github.io/php-mock-prophecy/api/class-phpmock.prophecy.PHPProphet.html#_define)
+  before that first call. This would define a side effectless namespaced function.
 
 # License and authors
 
@@ -26,4 +60,3 @@ If you like this project and feel generous donate a few Bitcoins here:
 [1335STSwu9hST4vcMRppEPgENMHD2r1REK](bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK)
 
 [![Build Status](https://travis-ci.org/php-mock/php-mock-prophecy.svg?branch=master)](https://travis-ci.org/php-mock/php-mock-prophecy)
-

classes/FunctionProphecy.php

@@ -8,17 +8,18 @@
 use Prophecy\Prophecy\MethodProphecy;
 
 /**
- * Function prophecy.
+ * A function prophecy.
  *
  * @author Markus Malkusch <[email protected]>
  * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
  * @license http://www.wtfpl.net/txt/copying/ WTFPL
+ * @internal
  */
-class FunctionProphecy implements ProphecyInterface
+final class FunctionProphecy implements ProphecyInterface
 {
 
     /**
-     * @var Prophet The prophet 
+     * @var Prophet The prophet.
      */
     private $prophet;
 
@@ -35,9 +36,8 @@ class FunctionProphecy implements ProphecyInterface
     /**
      * Sets the prophet.
      *
-     * @param string  $namespace The namespace.
-     * @param Prophet $prophet   The prophet.
-     * @internal
+     * @param string  $namespace function namespace
+     * @param Prophet $prophet   prophet
      */
     public function __construct($namespace, Prophet $prophet)
     {
@@ -46,12 +46,13 @@ public function __construct($namespace, Prophet $prophet)
     }
 
     /**
-     * Creates a new function prophecy using specified function name and arguments.
+     * Creates a new function prophecy using the specified function name
+     * and arguments.
      *
-     * @param string $functionName The function name.
-     * @param array  $arguments    The arguments.
+     * @param string $functionName function name
+     * @param array  $arguments    arguments
      *
-     * @return MethodProphecy The function prophecy.
+     * @return MethodProphecy function prophecy
      */
     public function __call($functionName, array $arguments)
     {
@@ -64,7 +65,7 @@ public function __call($functionName, array $arguments)
 
     /**
      * Reveals the function prophecies.
-     * 
+     *
      * I.e. the prophesized functions will become effective.
      */
     public function reveal()

classes/PHPProphet.php

@@ -3,17 +3,31 @@
 namespace phpmock\prophecy;
 
 use phpmock\MockRegistry;
+use phpmock\MockBuilder;
 use Prophecy\Prophet;
+use Prophecy\Prophecy\ProphecyInterface;
 use Prophecy\Exception\Prediction\AggregateException;
 
 /**
- * PHPProphet creates prophecies for functions. 
+ * A Prophet for built-in PHP functions.
+ *
+ * Example:
+ * <code>
+ * $prophet = new PHPProphet();
+ *
+ * $prophecy = $prophet->prophesize(__NAMESPACE__);
+ * $prophecy->time()->willReturn(123);
+ * $prophecy->reveal();
+ *
+ * assert(123 == time());
+ * $prophet->checkPredictions();
+ * <code>
  *
  * @author Markus Malkusch <[email protected]>
  * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
  * @license http://www.wtfpl.net/txt/copying/ WTFPL
  */
-class PHPProphet
+final class PHPProphet
 {
 
     /**
@@ -22,21 +36,27 @@ class PHPProphet
     private $prophet;
 
     /**
-     * Sets an optional prophet.
-     * 
-     * @param Prophet $prophet The prophet.
+     * Builds the prophet.
+     *
+     * @param Prophet|null $prophet optional proxied prophet
      */
     public function __construct(Prophet $prophet = null)
     {
-        $this->prophet = is_null($prophet) ? new Prophet() : $prophet;
+        if (is_null($prophet)) {
+            $prophet = new Prophet();
+        }
+        
+        $revealer = new ReferencePreservingRevealer(self::getProperty($prophet, "revealer"));
+        $util     = self::getProperty($prophet, "util");
+        $this->prophet = new Prophet($prophet->getDoubler(), $revealer, $util);
     }
 
     /**
-     * Creates a new function prophecy.
-     * 
-     * @param string $namespace The function namespace.
-     * 
-     * @return FunctionProphecy The function prophecy.
+     * Creates a new function prophecy for a given namespace.
+     *
+     * @param string $namespace function namespace
+     *
+     * @return ProphecyInterface function prophecy
      */
     public function prophesize($namespace)
     {
@@ -47,12 +67,56 @@ public function prophesize($namespace)
      * Checks all predictions defined by prophecies of this Prophet.
      *
      * It will also disable all previously revealed function prophecies.
-     * 
-     * @throws AggregateException If any prediction fails
+     *
+     * @throws AggregateException If any prediction fails.
      */
     public function checkPredictions()
     {
         MockRegistry::getInstance()->unregisterAll();
         $this->prophet->checkPredictions();
     }
+    
+    /**
+     * Defines the function prophecy in the given namespace.
+     *
+     * In most cases you don't have to call this method. {@link prophesize()}
+     * is doing this for you. But if the prophecy is defined after the first
+     * call in the tested class, the tested class doesn't resolve to the prophecy.
+     * This is documented in Bug #68541. You therefore have to define
+     * the namespaced function before the first call.
+     *
+     * Defining the function has no side effects. If the function was
+     * already defined this method does nothing.
+     *
+     * @param string $namespace function namespace
+     * @param string $name      function name
+     *
+     * @see prophesize()
+     * @link https://bugs.php.net/bug.php?id=68541 Bug #68541
+     */
+    public static function define($namespace, $name)
+    {
+        $builder = new MockBuilder();
+        $builder->setNamespace($namespace)
+            ->setName($name)
+            ->setFunction(function () {
+            })
+            ->build()
+            ->define();
+    }
+    
+    /**
+     * Returns a private property of a prophet.
+     *
+     * @param Prophet $prophet  prophet
+     * @param string  $property property name
+     *
+     * @return mixed property value of that prophet
+     */
+    private static function getProperty(Prophet $prophet, $property)
+    {
+        $reflection = new \ReflectionProperty($prophet, $property);
+        $reflection->setAccessible(true);
+        return $reflection->getValue($prophet);
+    }
 }

classes/ReferencePreservingRevealer.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace phpmock\prophecy;
+
+use Prophecy\Prophecy\RevealerInterface;
+
+/**
+ * Revealer proxy which keeps references.
+ *
+ * @author Markus Malkusch <[email protected]>
+ * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
+ * @license http://www.wtfpl.net/txt/copying/ WTFPL
+ * @internal
+ */
+final class ReferencePreservingRevealer implements RevealerInterface
+{
+    
+    /**
+     * @var RevealerInterface The subject.
+     */
+    private $revealer;
+    
+    /**
+     * Sets the subject.
+     *
+     * @param RevealerInterface $revealer proxied revealer
+     */
+    public function __construct(RevealerInterface $revealer)
+    {
+        $this->revealer = $revealer;
+    }
+
+    /**
+     * @SuppressWarnings(PHPMD)    
+     */
+    public function reveal($value)
+    {
+        if (is_array($value)) {
+            foreach ($value as &$item) {
+                $item = $this->revealer->reveal($item);
+            }
+            return $value;
+
+        } else {
+            return $this->revealer->reveal($value);
+        }
+    }
+}

classes/Revelation.php

@@ -7,14 +7,14 @@
 use Prophecy\Prophecy\ProphecyInterface;
 
 /**
- * The single function revelation.
+ * A function revelation.
  *
  * @author Markus Malkusch <[email protected]>
  * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
  * @license http://www.wtfpl.net/txt/copying/ WTFPL
  * @internal
  */
-class Revelation implements ProphecyInterface
+final class Revelation implements ProphecyInterface
 {
 
     /**
@@ -28,16 +28,16 @@ class Revelation implements ProphecyInterface
     private $functionName;
 
     /**
-     * @var ProphecyInterface The prophecy
+     * @var ProphecyInterface The prophecy.
      */
     private $prophecy;
 
     /**
-     * Setup the revelation.
-     * 
-     * @param String $namespace           The namespace.
-     * @param String $functionName        The function name.
-     * @param ProphecyInterface $prophecy The prophecy.
+     * Builds the revelation.
+     *
+     * @param String $namespace           function namespace
+     * @param String $functionName        function name
+     * @param ProphecyInterface $prophecy prophecy
      */
     public function __construct($namespace, $functionName, ProphecyInterface $prophecy)
     {
@@ -48,10 +48,10 @@ public function __construct($namespace, $functionName, ProphecyInterface $prophe
 
     /**
      * Reveals the function prophecy.
-     * 
+     *
      * I.e. the prophesized function will become effective.
-     * 
-     * @return Mock The enabled function mock.
+     *
+     * @return Mock enabled function mock
      */
     public function reveal()
     {

tests/PHPProphetTest.php

@@ -6,7 +6,7 @@
 use Prophecy\Argument;
 
 /**
- * Tests PHPProphet.
+ * A tests for PHPProphet.
  *
  * @author Markus Malkusch <[email protected]>
  * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
@@ -17,7 +17,7 @@ class PHPProphetTest extends AbstractMockTest
 {
 
     /**
-     * @var PHPProphet The SUT. 
+     * @var PHPProphet The SUT.
      */
     private $prophet;
 
@@ -36,9 +36,14 @@ protected function disableMocks()
     protected function mockFunction($namespace, $functionName, callable $function)
     {
         $prophecy = $this->prophet->prophesize($namespace);
-        $prophecy->$functionName(Argument::cetera())->will(function(array $parameters) use ($function) {
+        $prophecy->$functionName(Argument::cetera())->will(function (array $parameters) use ($function) {
             return call_user_func_array($function, $parameters);
         });
         $prophecy->reveal();
     }
+
+    protected function defineFunction($namespace, $functionName)
+    {
+        PHPProphet::define($namespace, $functionName);
+    }
 }