{"id":13828371,"url":"https://github.com/NielsdeBlaauw/php-doc-check","last_synced_at":"2025-07-09T06:31:46.378Z","repository":{"id":57026891,"uuid":"166038498","full_name":"NielsdeBlaauw/php-doc-check","owner":"NielsdeBlaauw","description":"Uses complexity metrics to determine which functions need documentation.","archived":false,"fork":false,"pushed_at":"2024-05-23T14:23:25.000Z","size":89,"stargazers_count":42,"open_issues_count":11,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-17T08:52:03.669Z","etag":null,"topics":["automated-testing","ci","cyclomatic-complexity","docblock","docblocks","hacktoberfest","metrics","php","score"],"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/NielsdeBlaauw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-16T12:42:35.000Z","updated_at":"2024-09-10T16:03:57.000Z","dependencies_parsed_at":"2024-06-18T20:11:36.777Z","dependency_job_id":null,"html_url":"https://github.com/NielsdeBlaauw/php-doc-check","commit_stats":{"total_commits":38,"total_committers":3,"mean_commits":"12.666666666666666","dds":"0.39473684210526316","last_synced_commit":"39615babda63a605da77e6c75ceacf15032e1bfb"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NielsdeBlaauw%2Fphp-doc-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NielsdeBlaauw%2Fphp-doc-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NielsdeBlaauw%2Fphp-doc-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NielsdeBlaauw%2Fphp-doc-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NielsdeBlaauw","download_url":"https://codeload.github.com/NielsdeBlaauw/php-doc-check/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225492420,"owners_count":17482869,"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":["automated-testing","ci","cyclomatic-complexity","docblock","docblocks","hacktoberfest","metrics","php","score"],"created_at":"2024-08-04T09:02:43.477Z","updated_at":"2024-11-20T08:30:27.160Z","avatar_url":"https://github.com/NielsdeBlaauw.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# php-doc-check\n\n[![Latest Stable Version](https://poser.pugx.org/niels-de-blaauw/php-doc-check/v/stable)](https://packagist.org/packages/niels-de-blaauw/php-doc-check)\n[![Build Status](https://travis-ci.org/NielsdeBlaauw/php-doc-check.svg?branch=master)](https://travis-ci.org/NielsdeBlaauw/php-doc-check)\n[![License](https://poser.pugx.org/niels-de-blaauw/php-doc-check/license)](https://packagist.org/packages/niels-de-blaauw/php-doc-check)\n\nPHP Doc Check is an automated command line tool to determine which functions and\nmethods could use some more documentation. \n\nBy default this script:\n\n- Emits a warning if there is no docblock for non trivial functions (score \u003e 4)\n- Emits an error if there is no docblock for complex functions (score \u003e 6)\n\nYou can gradually improve documenation on projects by starting with relatively\nhigh limits and slowly moving these limits down.\n\n## Metrics\n\n- [Cognitive Complexity](https://www.sonarsource.com/docs/CognitiveComplexity.pdf) `\u003cdefault\u003e` is \nused to find functions that are complex to read and understand.\n- [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) is \nused to find complex functions with a more traditionl algorithm.\n\n\n## Installation\n\n### Composer\n\nFor now you have to install the beta version.\n\n`composer require --dev niels-de-blaauw/php-doc-check:^0.2.0@dev`\n\n### Phive\n\n`phive install php-doc-check`\n\n## Usage\n\n```\n$vendor/bin/php-doc-check -?\nUsage: vendor/bin/php-doc-check [options] \u003cdirectory\u003e [\u003cdirectory\u003e...]\n\nOptions:\n  -x, --exclude \u003carg\u003e                       Directories to exclude, without\n                                            slash\n  -f, --format \u003carg\u003e                        Output format [text, json]\n                                            [default: text]\n  -o, --reportFile \u003carg\u003e                    Send report output to a file\n  -m, --metric \u003carg\u003e                        Metric to use for determining\n                                            complexity\n                                            [metrics.complexity.cognitive,\n                                            metrics.complexity.cyclomatic,\n                                            metrics.deprecated.category,\n                                            metrics.deprecated.subpackage,\n                                            metrics.complexity.length]\n                                            [default:\n                                            metrics.complexity.cognitive]\n  -w, --complexity-warning-threshold \u003carg\u003e  Cyclomatic complexity score which\n                                            is the lower bound for a warning\n                                            [default: 4]\n  -e, --complexity-error-threshold \u003carg\u003e    Cyclomatic complexity score which\n                                            is the lower bound for an error\n                                            [default: 6]\n  -$, --file-extension \u003carg\u003e                Valid file extensions to scan\n                                            [default: php]\n  -g, --grouping-method \u003carg\u003e               Allows different grouping of the\n                                            results list [file, none, metric,\n                                            severity, fileline] [default: file]\n  -s, --sorting-method \u003carg\u003e                Sorting for the results. Natural\n                                            sorts by name for groups and line\n                                            for findings. Value uses the\n                                            cumulative group score, and finding\n                                            score as sorting value. [natural,\n                                            value] [default: natural]\n  -i, --ignore-violations-on-exit           Will exit with a zero code, even if\n                                            any violations are found\n  -a, --ignore-anonymous-functions          Skip checks on anonymous functions\n  -?, --help                                Show this help and quit\n  -q, --quiet                               Don't show any output\n```\n\nExample first use: `vendor/bin/php-doc-check --exclude vendor ./`\n\n## Examples\n\nThis is fine without docblocks (trivial method)\n\n```php\npublic function get_title() : string{\n    return strtoupper($this-\u003etitle);\n}\n```\n\nThis could use some explanation\n\n```php\n/**\n * Limits the length of the title to a normal sentence, because older titles\n * tend to be longer then we can currently show.\n */\npublic function get_title() : string{\n    if(strlen($this-\u003etitle) \u003e 20 ){\n        if(strpos($this-\u003etitle,'.') !== false \u0026\u0026 strpos($this-\u003etitle,'.') \u003c 20){\n            [$title] = explode('.', $this-\u003etitle, 2);\n        }else{\n            $title = substr($this-\u003etitle, 0, 17) . '...';\n        }\n    }else{\n        $title = $this-\u003etitle;\n    }\n    return strtoupper($title);\n}\n```\n\n## FAQ\n\nQ: Why dont you want if there is no comment at all, regardless of complexity?\n\nA: You can set this software to warn for all functions that are undocumented by\nsetting `--complexity-error-threshold 1`. However, if you want to force\ndocumentation, you probably want to look into a tool like [php CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)\nin combination with documentation standards.\n\nQ: Why isn't there a warning/error about complex functions and refactoring, \nregardless if they have a DocBlock?\n\nA: You *should* refactor very complex functions. However, adding DocBlocks\nfor complex function is often easier and safer. This tool only checks the \navailability of this type of documentation. Other tools, like [php Mess Detector](https://github.com/phpmd/phpmd), \ncan help you limit complexity.\n\n## Issues\n\nIssues are in the GitHub tracker: https://github.com/NielsdeBlaauw/php-doc-check/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNielsdeBlaauw%2Fphp-doc-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNielsdeBlaauw%2Fphp-doc-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNielsdeBlaauw%2Fphp-doc-check/lists"}