roave / you-are-using-it-wrong
Composer plugin enforcing strict type checks in downstream package dependants
Installs: 62 903
Dependents: 1
Suggesters: 0
Security: 0
Stars: 238
Watchers: 11
Forks: 10
Open Issues: 4
Type:composer-plugin
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0
- composer-plugin-api: ^2.1.0
- ext-json: *
- ocramius/package-versions: ^2.8.0
- psalm/plugin-phpunit: ^0.18.4
- vimeo/psalm: ^5.19.1
Requires (Dev)
- composer/composer: ^2.6.6
- doctrine/coding-standard: ^12.0.0
- infection/infection: ^0.27.9
- phpunit/phpunit: ^10.5.7
- symfony/process: ^7.0.2
- 1.16.x-dev
- 1.15.x-dev
- 1.15.0
- 1.14.x-dev
- 1.14.0
- 1.13.x-dev
- 1.13.0
- 1.12.x-dev
- 1.12.0
- 1.11.x-dev
- 1.11.0
- 1.10.x-dev
- 1.10.0
- 1.9.x-dev
- 1.9.2
- 1.9.1
- 1.9.0
- 1.8.x-dev
- 1.8.0
- 1.7.x-dev
- 1.7.0
- 1.6.x-dev
- 1.6.0
- 1.5.x-dev
- 1.5.0
- 1.4.0
- 1.3.0
- 1.2.0
- 1.1.0
- 1.0.0
- dev-renovate/packagist-symfony-process-vulnerability
- dev-renovate/all-minor-patch
- dev-renovate/phpunit-phpunit-11.x
- dev-renovate/lock-file-maintenance
This package is auto-updated.
Last update: 2024-11-06 19:07:55 UTC
README
This package enforces type checks during composer installation in downstream consumers of your package. This only applies to usages of classes, properties, methods and functions declared within packages that directly depend on roave/you-are-using-it-wrong.
Issues that the static analyser finds that do not relate to these namespaces will not be reported.
roave/you-are-using-it-wrong
comes with a zero-configuration out-of-the-box
setup.
By default, it hooks into composer install
and composer update
, preventing
a successful command execution if there are type errors in usages of protected
namespaces.
The usage of this plugin is highly endorsed for authors of new PHP libraries who appreciate the advantages of static types.
This project is built with the hope that libraries with larger user-bases will raise awareness of type safety (or current lack thereof) in the PHP ecosystem.
As annoying as it might sound, it is not uncommon for library maintainers to respond to support questions caused by lack of type checks in downstream projects. In addition to that, relying more on static types over runtime checks, it is possible to reduce code size and maintenance burden by strengthening the API boundaries of a library.
Installation
This package is designed to be installed as a dependency of PHP libraries.
In your library, add it to your
composer.json
:
composer require roave/you-are-using-it-wrong
No further changes are needed for this tool to start operating as per its design, if your declared types are already reflecting your library requirements.
Please also note that this should not be used in "require-dev"
, but
specifically in "require"
in order for the type checks to be applied to
downstream consumers of your code.
Examples
You can experiment with the following example by running cd examples && ./run-example.sh
.
Given you are the author of my/awesome-library
, which has following composer.json
:
{ "name": "my/awesome-library", "type": "library", "autoload": { "psr-4": { "My\\AwesomeLibrary\\": "src" } }, "require": { "roave/you-are-using-it-wrong": "^1.0.0" } }
Given following my/awesome-library/src/MyHelloWorld.php
:
<?php declare(strict_types=1); namespace My\AwesomeLibrary; final class MyHelloWorld { /** @param array<string> $people */ public static function sayHello(array $people) : string { return 'Hello ' . implode(', ', $people) . '!'; } }
Given following downstream a/project/composer.json
project that
depends on your my/awesome-library
:
{ "name": "a/project", "type": "project", "autoload": { "psr-4": { "The\\Project\\": "src" } }, "require": { "my/awesome-library": "^1.0.0" } }
And following a/project/src/MyExample.php
:
<?php declare(strict_types=1); // notice the simple type error echo \My\AwesomeLibrary\MyHelloWorld::sayHello([123, 456]);
Then composer install
in said project will fail:
$ cd a/project $ composer install Loading composer repositories with package information Updating dependencies (including require-dev) ... <snip> - Installing roave/you-are-using-it-wrong (1.0.0): ... - Installing my/awesome-library (1.0.0): ... ... <snip> roave/you-are-using-it-wrong: checking strictly type-checked packages... Scanning files... Analyzing files... ERROR: InvalidScalarArgument - a-project/src/MyExample.php:4:48 - Argument 1 of My\AwesomeLibrary\MyHelloWorld::sayhello expects array<array-key, string>, array{0:int(123), 1:int(456)} provided echo \My\AwesomeLibrary\MyHelloWorld::sayHello([123, 456]); $ echo $? 1
Workarounds
This package is designed to be quite invasive from a type-check perspective,
but it will bail out of any checks if a psalm configuration
is detected in the root of the installation/project.
If that is the case, the tool assumes that the author of the project is already
responsible for ensuring type-safety within their own domain, and therefore
bails out without performing further checks.
As mentioned above, the design of the tool circles around raising awareness of static type usage in the PHP ecosystem, and therefore it will only give up if it is sure that library consumers are already taking care of the matter on their own.
Professional Support
If you need help with setting up this library in your project, you can contact us at team@roave.com for consulting/support.