{"id":13828285,"url":"https://github.com/Roave/you-are-using-it-wrong","last_synced_at":"2025-07-09T06:31:27.327Z","repository":{"id":34858044,"uuid":"184848377","full_name":"Roave/you-are-using-it-wrong","owner":"Roave","description":":oncoming_police_car: Type check enforcement for library authors: enforces type-safety downstream","archived":false,"fork":false,"pushed_at":"2024-11-17T12:33:10.000Z","size":568,"stargazers_count":238,"open_issues_count":5,"forks_count":10,"subscribers_count":11,"default_branch":"1.16.x","last_synced_at":"2024-11-17T13:32:46.717Z","etag":null,"topics":[],"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/Roave.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-05-04T03:37:35.000Z","updated_at":"2024-09-05T14:22:16.000Z","dependencies_parsed_at":"2023-10-26T11:42:32.098Z","dependency_job_id":"bae2d966-f240-495a-8564-39812ca5fbd3","html_url":"https://github.com/Roave/you-are-using-it-wrong","commit_stats":{"total_commits":209,"total_committers":13,"mean_commits":"16.076923076923077","dds":0.5502392344497608,"last_synced_commit":"8a5be47e99d1e748dcc9da81b64f7d0c79ce30d3"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2Fyou-are-using-it-wrong","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2Fyou-are-using-it-wrong/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2Fyou-are-using-it-wrong/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2Fyou-are-using-it-wrong/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Roave","download_url":"https://codeload.github.com/Roave/you-are-using-it-wrong/tar.gz/refs/heads/1.16.x","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":[],"created_at":"2024-08-04T09:02:39.802Z","updated_at":"2024-11-20T08:30:22.900Z","avatar_url":"https://github.com/Roave.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# roave/you-are-using-it-wrong\n\n[![Mutation testing badge](https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Froave%2Fyou-are-using-it-wrong)](https://dashboard.stryker-mutator.io/reports/github.com/roave/you-are-using-it-wrong/master)\n[![Type Coverage](https://shepherd.dev/github/roave/you-are-using-it-wrong/coverage.svg)](https://shepherd.dev/github/roave/you-are-using-it-wrong)\n[![Packagist](https://img.shields.io/packagist/v/roave/you-are-using-it-wrong.svg)](https://packagist.org/packages/roave/you-are-using-it-wrong)\n\nThis package enforces type checks during composer installation in downstream\nconsumers of your package. This only applies to usages of classes, properties,\nmethods and functions declared within packages that directly depend on\n*roave/you-are-using-it-wrong*.\n\nIssues that the static analyser finds that do not relate to these namespaces\nwill not be reported.\n\n`roave/you-are-using-it-wrong` comes with a zero-configuration out-of-the-box\nsetup.\n\nBy default, it hooks into `composer install` and `composer update`, preventing\na successful command execution if there are type errors in usages of protected\nnamespaces. \n\nThe usage of this plugin is highly endorsed for authors of new PHP libraries\nwho appreciate the advantages of static types.\n\nThis project is built with the hope that libraries with larger user-bases will\nraise awareness of type safety (or current lack thereof) in the PHP ecosystem.\n\nAs annoying as it might sound, it is not uncommon for library maintainers to\nrespond to support questions caused by lack of type checks in downstream\nprojects. In addition to that, relying more on static types over runtime checks,\nit is possible to reduce code size and maintenance burden by strengthening the\nAPI boundaries of a library.\n\n### Installation\n\nThis package is designed to be installed as a dependency of PHP **libraries**.\n\nIn your library, add it to your\n`composer.json`:\n\n```sh\ncomposer require roave/you-are-using-it-wrong\n```\n\nNo further changes are needed for this tool to start operating as per its\ndesign, if your declared types are already reflecting your library requirements.\n\nPlease also note that this should **not** be used in `\"require-dev\"`, but\nspecifically in `\"require\"` in order for the type checks to be applied to\ndownstream consumers of your code.\n\n### Examples\n\nYou can experiment with the following example by running `cd examples \u0026\u0026 ./run-example.sh`.\n\nGiven you are the author of `my/awesome-library`, which has following `composer.json`:\n\n```json\n{\n    \"name\": \"my/awesome-library\",\n    \"type\": \"library\",\n    \"autoload\": {\n        \"psr-4\": {\n            \"My\\\\AwesomeLibrary\\\\\": \"src\"\n        }\n    },\n    \"require\": {\n        \"roave/you-are-using-it-wrong\": \"^1.0.0\"\n    }\n}\n```\n\nGiven following `my/awesome-library/src/MyHelloWorld.php`:\n\n```php\n\u003c?php declare(strict_types=1);\n\nnamespace My\\AwesomeLibrary;\n\nfinal class MyHelloWorld\n{\n    /** @param array\u003cstring\u003e $people */\n    public static function sayHello(array $people) : string\n    {\n        return 'Hello ' . implode(', ', $people) . '!';\n    }\n}\n```\n\nGiven following downstream `a/project/composer.json` project that\ndepends on your `my/awesome-library`:\n\n```json\n{\n    \"name\": \"a/project\",\n    \"type\": \"project\",\n    \"autoload\": {\n        \"psr-4\": {\n            \"The\\\\Project\\\\\": \"src\"\n        }\n    },\n    \"require\": {\n        \"my/awesome-library\": \"^1.0.0\"\n    }\n}\n```\n\nAnd following `a/project/src/MyExample.php`:\n\n```php\n\u003c?php declare(strict_types=1);\n\n// notice the simple type error\necho \\My\\AwesomeLibrary\\MyHelloWorld::sayHello([123, 456]);\n```\n\nThen `composer install` in said project will fail:\n\n```sh\n$ cd a/project\n$ composer install\n\nLoading composer repositories with package information\nUpdating dependencies (including require-dev)\n  ... \u003csnip\u003e\n  - Installing roave/you-are-using-it-wrong (1.0.0): ...\n  - Installing my/awesome-library (1.0.0): ...\n  ... \u003csnip\u003e\n\nroave/you-are-using-it-wrong: checking strictly type-checked packages...\nScanning files...\nAnalyzing files...\n\nERROR: InvalidScalarArgument - a-project/src/MyExample.php:4:48 \n  - Argument 1 of My\\AwesomeLibrary\\MyHelloWorld::sayhello expects array\u003carray-key, string\u003e,\n    array{0:int(123), 1:int(456)} provided\necho \\My\\AwesomeLibrary\\MyHelloWorld::sayHello([123, 456]);\n\n$ echo $?\n1\n```\n\n## Workarounds\n\nThis package is designed to be quite invasive from a type-check perspective,\nbut it will bail out of any checks if a [`psalm configuration`](https://psalm.dev/docs/configuration/)\nis detected in the root of the installation/project.\nIf that is the case, the tool assumes that the author of the project is already\nresponsible for ensuring type-safety within their own domain, and therefore\nbails out without performing further checks.\n\nAs mentioned above, the design of the tool circles around raising awareness of\nstatic type usage in the PHP ecosystem, and therefore it will only give up if\nit is sure that library consumers are already taking care of the matter on their\nown.\n\n## Professional Support\n\nIf you need help with setting up this library in your project, you can contact\nus at team@roave.com for consulting/support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRoave%2Fyou-are-using-it-wrong","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRoave%2Fyou-are-using-it-wrong","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRoave%2Fyou-are-using-it-wrong/lists"}