{"id":17696822,"url":"https://github.com/datashaman/phpcheck","last_synced_at":"2026-01-20T00:33:33.572Z","repository":{"id":56962826,"uuid":"181292116","full_name":"datashaman/phpcheck","owner":"datashaman","description":"PHP implementation of Haskell's QuickCheck.","archived":false,"fork":false,"pushed_at":"2019-05-11T03:58:23.000Z","size":1221,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-13T11:53:53.743Z","etag":null,"topics":["fuzz-testing","fuzzing-framework","quickcheck"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datashaman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-14T10:23:55.000Z","updated_at":"2023-05-24T15:39:17.000Z","dependencies_parsed_at":"2022-08-21T08:20:48.924Z","dependency_job_id":null,"html_url":"https://github.com/datashaman/phpcheck","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fphpcheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fphpcheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fphpcheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fphpcheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datashaman","download_url":"https://codeload.github.com/datashaman/phpcheck/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615483,"owners_count":20967183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzz-testing","fuzzing-framework","quickcheck"],"created_at":"2024-10-24T14:45:26.575Z","updated_at":"2026-01-20T00:33:33.531Z","avatar_url":"https://github.com/datashaman.png","language":"PHP","readme":"# phpcheck\n\n![Development Status](https://img.shields.io/badge/status-alpha-red.svg)\n[![Build Status](https://travis-ci.org/datashaman/phpcheck.svg?branch=master)](https://travis-ci.org/datashaman/phpcheck)\n\nPHP implementation of Haskell's QuickCheck.\n\n*NB* This is *ALPHA* status. Do not use it yet.\n\nTable of Contents\n=================\n\n   * [phpcheck](#phpcheck)\n      * [installation](#installation)\n      * [type declarations](#type-declarations)\n      * [annotations](#annotations)\n        * [tabulate](#tabulate)\n      * [generators](#generators)\n      * [assertions](#assertions)\n      * [examples](#examples)\n      * [command line arguments](#command-line-arguments)\n      * [storage of results](#storage-of-results)\n      * [todo](#todo)\n\n## installation\n\nInstall the composer package into your project. You will require `PHP7.2` or higher:\n\n    composer require --dev datashaman/phpcheck\n\nAlternately, you can install the composer package globally:\n\n    composer global require datashaman/phpcheck\n\n## type declarations\n\n`PHPCheck` will automatically generate arguments for check methods based on type declarations.\n\nFor finer-grained control over the arguments, use annotations on the method parameters.\n\n## annotations\n\nAnnotate your check method parameters to control the arguments provided to the method.\n\nParameter tags (use them in the description of a parameter, usually the end):\n\n* `{@gen method()}` or `{@gen method(1, 10)}` where `method` is the name of a generator below.\n\nMethod tags:\n\n* `@maxSuccess` sets the number of successful checks for a successful result. The default is 100.\n* `@tabulate` and `@coverTable` (dicussed below).\n\n### tabulate\n\nIf you decorate a check method with `tabulate`, information about test case distribution is collected into a table.\n\nThe arguments to `tabulate` are the table's name and a _list_ of values associated with the current check. An example:\n\n    /**\n     * @tabulate \"Values\" [$value]\n     */\n    public function checkBooleans(bool $value)\n    {\n        return true;\n    }\n\nIf you run this check, everything passes and a table is output at the end of the check run:\n\n    Tables\n\n    1) Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleans\n\n    Values (100 total)\n\n       52% true\n       48% false\n\nWe'd like to check that the coverage is correct for the generator, so we use a `@coverTable` method annotation:\n\n    /**\n     * @coverTable \"Values\" [[true, 49], [false, 49]]\n     * @tabulate \"Values\" [$value]\n     */\n    public function checkBooleans(bool $value)\n    {\n        return true;\n    }\n\nThe arguments to the annotation are the name of the table, and a list of key value pairs where the value is the expected percentage distribution.\n\nHere's a sample output from the above:\n\n    1) Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleans\n\n    Values (100 total)\n\n    54% true\n    46% false\n\n    Table 'Values' had only 46.0% false, but expected 49.0%\n\nWe are now warned when the distribution does not fall within the accepted percentage of generated values.\n\nIn this case, we would benefit from running the checks a lot more times so we approach the expected _50/50_ average for a boolean:\n\n    /**\n     * @coverTable \"Values\" [[true, 49], [false, 49]]\n     * @maxSuccess 10000\n     * @tabulate \"Values\" [$value]\n     */\n    public function checkBooleans(bool $value)\n    {\n        return true;\n    }\n\nNow with _10000_ successful iterations, the warning disappears from the output and the percentage is within the acceptable _1%_ margin of error:\n\n    1) Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleans\n\n    Values (10000 total)\n\n        50.5% true\n        49.5% false\n\n## generators\n\nBelow is the list of generators that are currently available:\n\n* `arguments(callable $callable)`\n* `arrays()`\n* `ascii()`\n* `booleans(int $chanceOfGettingTrue = 50)`\n* `characters($minChar = null, $maxChar = null)`\n* `choose($min = PHP_INT_MIN, $max = PHP_INT_MAX)`\n* `chooseAny(string $type)`\n* `datetimes($min = null, $max = null, Generator $timezones = null)`\n* `dates($min = null, $max = null)`\n* `elements(array $array)`\n* `faker(...$args)`\n* `floats(float $min, float $max)`\n* `frequency(array $frequencies)`\n* `growingElements(array $array)`\n* `integers(int $min = PHP_INT_MIN, int $max = PHP_INT_MAX)`\n* `intervals(array $include = [[PHP_INT_MIN, PHP_INT_MAX]], array $exclude=[])`\n* `listOf(Generator $gen)`\n* `listOf1(Generator $gen)`\n* `mixed()`\n* `oneof(array $gens)`\n* `resize(int $n, Generator $gen)`\n* `scale(callable $f, Generator $gen)`\n* `strings(Generator $characters = null)`\n* `suchThat(Generator $gen, callable $f)`\n* `suchThatMap(Generator $gen, callable $f)`\n* `suchThatMaybe(Generator $gen, callable $f)`\n* `timezones()`\n* `variant(int $seed, Generator $gen)`\n* `vectorOf(int $n, Generator $gen)`\n\nTo generate a value from one of the above, use `generate`:\n\n    \u003e\u003e\u003e use function Datashaman\\PHPCheck\\{\n    ...     choose,\n    ...     generate\n    ... };\n    \u003e\u003e\u003e\n    \u003e\u003e\u003e var_dump(generate(choose(0, 10)));\n    int(2)\n\nTo generate a sample of values with increasing size, use `sample`:\n\n    \u003e\u003e\u003e use function Datashaman\\PHPCheck\\{\n    ...     ascii,\n    ...     strings,\n    ...     sample\n    ... };\n    \u003e\u003e\u003e\n    \u003e\u003e\u003e var_dump(sample(strings(ascii())));\n    array(11) {\n    [0]=\u003e\n    string(0) \"\"\n    [1]=\u003e\n    string(2) \"0]\"\n    [2]=\u003e\n    string(2) \"^|\"\n    [3]=\u003e\n    string(3) \"P@N\"\n    [4]=\u003e\n    string(5) \"G1KPu\"\n    [5]=\u003e\n    string(5) \"q-e1y\"\n    [6]=\u003e\n    string(4) \"NcdL\"\n    [7]=\u003e\n    string(7) \"hS:{_\u003e@\"\n    [8]=\u003e\n    string(10) \"wjv1X\"Zm$V\"\n    [9]=\u003e\n    string(16) \"aX-6*s0-WX\u003e#cf~T\"\n    [10]=\u003e\n    string(12) \";g\u003c\u00268*b\u0026Q0=)\"\n    }\n    =\u003e null\n\nSee [GeneratorCheck](checks/GeneratorCheck.php) and [GeneratorTest](tests/GeneratorTest.php) for examples of how these are used.\n\nThe `characters` generator accepts either characters or integer codepoints for `minChar` and `maxChar`. Characters\nare generated from the complete range of Unicode characters excluding control characters, private ranges and surrogates.\n\nThe `faker` generator takes a variable number of arguments. If you supply one argument, it's assumed to be a property on the `Faker`\ngenerator. If you supply more than one argument, the first argument is the method on the `Faker` generator and the rest are sent as parameters to that method.\n\nThis opens up a lot of domain-specific generators. See [Faker](https://github.com/fzaninotto/Faker) for more details.\n\n## check methods\n\nCheck methods must return a bool indicating success or failure.\n\n## exceptions\n\nWe have chosen to use [Nuno Maduro's Collision](https://github.com/nunomaduro/collision) for reporting exceptions to the console.\n\nThis should be switchable soon.\n\n## examples\n\nThere is an example check implemented in the _examples_ folder. To run it:\n\n    phpcheck examples\n\nThe [_Generator_ checks](checks/GeneratorCheck.php) for this package are a great illustration of the use of the generators.\n\n## command line arguments\n\nThe `phpcheck` program accept a number of arguments and options:\n\n    Description:\n        Runs checks.\n\n    Usage:\n        phpcheck [options] [--] [\u003cpath\u003e]\n\n    Arguments:\n        path                           File or folder with checks [default: \"checks\"]\n\n    Options:\n            --bootstrap[=BOOTSTRAP]         A PHP script that is included before the checks run\n            --coverage-html[=COVERAGE-HTML] Generate HTML code coverage report [default: false]\n            --coverage-text[=COVERAGE-TEXT] Generate text code coverage report [default: false]\n        -f, --filter[=FILTER]               Filter the checks that will be run\n        -j, --log-junit[=LOG-JUNIT]         Log check execution to JUnit XML file [default: false]\n        -t, --log-text[=LOG-TEXT]           Log check execution to text file [default: false]\n        --max-success=MAX-SUCCESS           Maximum number of successful checks before succeeding. Testing stops at the first failure.\n                                            If all tests are passing and you want to run more tests, increase this number. [default: 100]\n        -d, --no-defects[=NO-DEFECTS]       Ignore previous defects [default: false]\n        -h, --help                          Display this help message\n        -q, --quiet                         Do not output any message\n        -s, --seed[=SEED]                   Seed the random number generator to get repeatable runs\n        -V, --version                       Display this application version\n        --ansi                              Force ANSI output\n        --no-ansi                           Disable ANSI output\n        -n, --no-interaction                Do not ask any interactive question\n        -v|vv|vvv, --verbose                Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nThe `--bootstrap` parameter can be included in a _phpcheck.xml_ or _phpcheck.xml.dist_ file. See [ours](phpcheck.xml.dist) for an example.\n\nThe `--filter` or `-f` parameter is a filename-style match as follows:\n\n    ClassName::\n    ClassName::MethodName\n    MethodName\n\nwhere `ClassName` and `MethodName` can include patterns using `*` and `?` as you'd expect.\n\nThe console reporter outputs check results much like `PHPUnit`:\n\n    PHPCheck 0.1.0 by Marlin Forbes and contributors.\n\n    .............\n\n    13 / 13 (100%)\n\n    Time: 284 ms, Memory: 6.00 MB\n\n    OK (Checks: 13, Iterations: 120006, Failures: 0, Errors: 0)\n\nUsing `---verbose 3` or `-vvv` enables a list of the checks as they are run:\n\n    PHPCheck 0.1.0 by Marlin Forbes and contributors.\n\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkCharacters' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkCharacters' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkStrings' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkStrings' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkAscii' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkAscii' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleans' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleans' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleansWithPercentage' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkBooleansWithPercentage' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkCharactersWithNumbers' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkCharactersWithNumbers' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkCharactersWithStrings' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkCharactersWithStrings' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkChoose' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkChoose' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkIterations' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkIterations' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkFloats' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkFloats' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkFloatsWithDecimalGen' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkFloatsWithDecimalGen' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkStringsWithMinMax' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkStringsWithMinMax' ended\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkListOfInts' started\n    Check 'Datashaman\\PHPCheck\\Checks\\GeneratorCheck::checkListOfInts' ended\n\n    Time: 305 ms, Memory: 6.00 MB\n\n    OK (Checks: 13, Iterations: 120006, Failures: 0, Errors: 0)\n\n## storage of results\n\n`PHPCheck` stores results of check execution in the `.phpcheck` folder of the project.\n\nYou should add the folder to your `.gitignore` file.\n\nWhen `PHPCheck` finds an error or failure, it will retry the defective arguments first before going onto regular iterations with new arguments.\n\nIf you wish to ignore the previous defects and run through new iterations only, use `--no-defects` or `-d`.\n\n## todo\n\nAll todo items have been captured as [issues](https://github.com/datashaman/phpcheck/issues).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatashaman%2Fphpcheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatashaman%2Fphpcheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatashaman%2Fphpcheck/lists"}