{"_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"}