As you can see there are a variety of methods for verifying that the appropriate parameters are being passed to methods. However, there may be times when the prebuilt constraints and matchers simply do not fit your needs. Perhaps there is method that accepts a complex object where only certain components of the object need to be validated. Parameter capturing will allow you to store the parameter that was used to call your method so that it can be used in assertions later on.

Consider the following example where I have defined a getNumberOfCards() method on the CardCollection interface.

I want to create new functionality for a my poker dealer strategy that will check to make sure we are playing with a full deck of 52 cards when the deal() call is made. It would be rather cumbersome to create a copy of a CardCollection implementation that I could be sure would match in an equals scenario. Such a test would look something like this.

Please note, I do not generally advocate this type of design. I prefer a dependency injection versus instantiation. So please remember, this is not an example of clean design, simply an example of what you can do with argument capturing.

You can also capture parameters if they meet a certain condition. For instance, if someone mistakenly passed an array as the first parameter to the deal() method then PHPUnit would fatal error out. This can be protected against by using the the Phake::capture()->when() method. The when() method accepts the same constraints that Phake::verify() accepts. Here is how you could leverage that functionality to bulletproof your captures a little bit.

This could also be done by using PHPUnit's assertions later on with the captured parameter, however this also has a side effect of better localizing your error. Here is the error you would see if the above test failed.

It should be noted that while it is possible to use argument capturing for stubbing with Phake::when() I would discourage it. When stubbing a method you should only be concerned about making sure an expected value is return and argument capturing in no way helps with that goal. In the worst case scenario you will have some incredibly difficult test failures to diagnose.