roave/you-are-using-it-wrong

Composer plugin enforcing strict type checks in downstream package dependants

1.15.0 2024-01-17 18:41 UTC

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

MIT

• Marco Pivetta

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 [e-mail] for consulting/support.