{"_id":"56b5370a5997532100bc6c30","githubsync":"","__v":4,"category":{"_id":"56b534f35f1cf00d00cc475d","__v":10,"project":"56b534f15f1cf00d00cc4759","version":"56b534f25f1cf00d00cc475c","pages":["56b534f45f1cf00d00cc475f","56b5368185a6922300d1c538","56b5369a168b5c1700c159a9","56b536b4eed075230097d75e","56b536c32d7fc00d0037f496","56b5370a5997532100bc6c30","56b537147bccae0d00e9a1d0","56b537252d7fc00d0037f498","56b5372e5997532100bc6c32","56b5373d7719bb190014307a"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-05T23:49:07.518Z","from_sync":false,"order":9999,"slug":"documentation","title":"Documentation"},"project":"56b534f15f1cf00d00cc4759","version":{"_id":"56b534f25f1cf00d00cc475c","project":"56b534f15f1cf00d00cc4759","__v":4,"createdAt":"2016-02-05T23:49:06.439Z","releaseDate":"2016-02-05T23:49:06.439Z","categories":["56b534f35f1cf00d00cc475d","56b55e5b5f1cf00d00cc477c","56b55e605f1cf00d00cc477d","56b5fac7e205510d001e4cfe"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"56b534d0168b5c1700c159a7","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-05T23:58:02.565Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Matchers are used to compare the return values of controls, to that of our trials. Ideally, we want our trials to replicate the functionality of our control in a much more efficient way. To ensure that we don't break our application, the return values **must** match.\n\nBy default, Scientist uses an instance of `Scientist\\Matchers\\StandardMatcher` to perform matching operations. Internally, it simply performs a strict `===` comparison on the return values of the control and the trial.\n\nIf you're using more complex objects, a simple strict `===` comparison might not be enough. Fortunately, Scientist offers the ability to create custom matchers that we can use in our experiments.\n\nTo create a custom matcher, we must extend the `Scientist\\Matchers\\Matcher` abstract class. Here's an example.\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\nnamespace MyApp;\\n\\nuse Scientist\\\\Matchers\\\\Matcher;\\n\\n/**\\n * Class StandardMatcher\\n *\\n * :::at:::package \\\\Scientist\\\\Matchers\\n */\\nclass MyMatcher implements Matcher\\n{\\n    /**\\n     * Determine whether two values match.\\n     *\\n     * @param mixed $control\\n     * @param mixed $trial\\n     *\\n     * @return boolean\\n     */\\n    public function match($control, $trial)\\n    {\\n        // Perform matching evaluation here.\\n    }\\n}\\n\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nHere, we've created a new matcher, for our own evil purposes.\n\nThe `match()` method, receives the value from the control, and the value from a trial. It's up to us to determine whether or not they match. We must implement the code that will return a boolean value.\n\nReturning a `true` boolean value will indicate a match, and experiments utilising this matcher will indicate a match within their result report. A return value of `false` will indicate that a match did not occur.\n\nLet's say that our application has a `User` class. This class contains a property for a users name, alongside a number of other properties and methods. A direct comparison will likely not be desired, as the object is fairly complex.\n\nInstead, we only wish to compare the name of the user. Let's define a matcher to accomplish this task.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\nnamespace MyApp;\\n\\nuse Scientist\\\\Matchers\\\\Matcher;\\n\\n/**\\n * Class StandardMatcher\\n *\\n * @package \\\\Scientist\\\\Matchers\\n */\\nclass UserMatcher implements Matcher\\n{\\n    /**\\n     * Determine whether two values match.\\n     *\\n     * @param mixed $control\\n     * @param mixed $trial\\n     *\\n     * @return boolean\\n     */\\n    public function match($control, $trial)\\n    {\\n        return $control->name == $trial->name;\\n    }\\n}\\n\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nIn our new matcher, we're checking to see if the user names match.\n\nWe'll need to apply this matcher to our experiment before we can use it. Don't worry. It's simple!\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n\\n$experiment = (new Scientist\\\\Laboratory)\\n  ->experiment('experiment title')\\n\\t->control($controlCallback)\\n  ->trial('trial name', $trialCallback)\\n  ->matcher(new \\\\MyApp\\\\UserMatcher);\\n\\n$value = $experiment->run();\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nSimply use the `matcher()` method on the experiment to attach our custom matcher. It will then replace the `StandardMatcher` for this experiment. Huzzah!","excerpt":"Matching controls to trials.","slug":"matchers","type":"basic","title":"Matchers"}

Matchers

Matching controls to trials.

Matchers are used to compare the return values of controls, to that of our trials. Ideally, we want our trials to replicate the functionality of our control in a much more efficient way. To ensure that we don't break our application, the return values **must** match. By default, Scientist uses an instance of `Scientist\Matchers\StandardMatcher` to perform matching operations. Internally, it simply performs a strict `===` comparison on the return values of the control and the trial. If you're using more complex objects, a simple strict `===` comparison might not be enough. Fortunately, Scientist offers the ability to create custom matchers that we can use in our experiments. To create a custom matcher, we must extend the `Scientist\Matchers\Matcher` abstract class. Here's an example. [block:code] { "codes": [ { "code": "<?php\n\nnamespace MyApp;\n\nuse Scientist\\Matchers\\Matcher;\n\n/**\n * Class StandardMatcher\n *\n * @package \\Scientist\\Matchers\n */\nclass MyMatcher implements Matcher\n{\n /**\n * Determine whether two values match.\n *\n * @param mixed $control\n * @param mixed $trial\n *\n * @return boolean\n */\n public function match($control, $trial)\n {\n // Perform matching evaluation here.\n }\n}\n", "language": "php" } ] } [/block] Here, we've created a new matcher, for our own evil purposes. The `match()` method, receives the value from the control, and the value from a trial. It's up to us to determine whether or not they match. We must implement the code that will return a boolean value. Returning a `true` boolean value will indicate a match, and experiments utilising this matcher will indicate a match within their result report. A return value of `false` will indicate that a match did not occur. Let's say that our application has a `User` class. This class contains a property for a users name, alongside a number of other properties and methods. A direct comparison will likely not be desired, as the object is fairly complex. Instead, we only wish to compare the name of the user. Let's define a matcher to accomplish this task. [block:code] { "codes": [ { "code": "<?php\n\nnamespace MyApp;\n\nuse Scientist\\Matchers\\Matcher;\n\n/**\n * Class StandardMatcher\n *\n * @package \\Scientist\\Matchers\n */\nclass UserMatcher implements Matcher\n{\n /**\n * Determine whether two values match.\n *\n * @param mixed $control\n * @param mixed $trial\n *\n * @return boolean\n */\n public function match($control, $trial)\n {\n return $control->name == $trial->name;\n }\n}\n", "language": "php" } ] } [/block] In our new matcher, we're checking to see if the user names match. We'll need to apply this matcher to our experiment before we can use it. Don't worry. It's simple! [block:code] { "codes": [ { "code": "<?php\n\n$experiment = (new Scientist\\Laboratory)\n ->experiment('experiment title')\n\t->control($controlCallback)\n ->trial('trial name', $trialCallback)\n ->matcher(new \\MyApp\\UserMatcher);\n\n$value = $experiment->run();", "language": "php" } ] } [/block] Simply use the `matcher()` method on the experiment to attach our custom matcher. It will then replace the `StandardMatcher` for this experiment. Huzzah!