Add capture argument matcher

docs/reference/argument_validation.rst

@@ -229,6 +229,27 @@ methods to call.
 
     There is no Hamcrest version of the ``ducktype()`` matcher.
 
+Capturing Arguments
+-------------------
+
+If we want to perform multiple validations on a single argument, the ``capture``
+matcher provides a streamlined alternative to using the ``on()`` matcher.
+It accepts a variable which the actual argument will be assigned.
+
+.. code-block:: php
+
+    $mock = \Mockery::mock('MyClass');
+    $mock->shouldReceive("foo")
+        ->with(\Mockery::capture($bar));
+
+This will assign *any* argument passed to ``foo`` to the local ``$bar`` variable to
+then perform additional validation using assertions.
+
+.. note::
+
+    The ``capture`` matcher always evaluates to ``true``. As such, we should always
+    perform additional argument validation.
+
 Additional Argument Matchers
 ----------------------------
 

library/Mockery.php

@@ -432,6 +432,23 @@ public static function hasValue($val)
         return new \Mockery\Matcher\HasValue($val);
     }
 
+    /**
+     * Return instance of CLOSURE matcher.
+     *
+     * @param $reference
+     *
+     * @return \Mockery\Matcher\Closure
+     */
+    public static function capture(&$reference)
+    {
+        $closure = function ($argument) use (&$reference) {
+            $reference = $argument;
+            return true;
+        };
+
+        return new \Mockery\Matcher\Closure($closure);
+    }
+
     /**
      * Return instance of CLOSURE matcher.
      *

tests/Mockery/ExpectationTest.php

@@ -1555,6 +1555,25 @@ public function testHasValueConstraintThrowsExceptionWhenConstraintUnmatched()
         Mockery::close();
     }
 
+    public function testCaptureStoresArgumentOfTypeScalar_ClosureEvaluatesToTrue()
+    {
+        $temp = null;
+        $this->mock->shouldReceive('foo')->with(Mockery::capture($temp))->once();
+        $this->mock->foo(4);
+
+        $this->assertSame(4, $temp);
+    }
+
+    public function testCaptureStoresArgumentOfTypeArgument_ClosureEvaluatesToTrue()
+    {
+        $object = new stdClass();
+        $temp = null;
+        $this->mock->shouldReceive('foo')->with(Mockery::capture($temp))->once();
+        $this->mock->foo($object);
+
+        $this->assertSame($object, $temp);
+    }
+
     public function testOnConstraintMatchesArgument_ClosureEvaluatesToTrue()
     {
         $function = function ($arg) {