README

此包在您的包的下游消费者中强制执行 Composer 安装期间的类型检查。这仅适用于在直接依赖于 roave/you-are-using-it-wrong 的包内声明的类、属性、方法和函数的使用。

静态分析器找到的与这些命名空间无关的问题将不会报告。

roave/you-are-using-it-wrong 随带零配置的默认设置。

默认情况下，它挂钩到 composer install 和 composer update，如果在受保护命名空间的使用中存在类型错误，则阻止命令成功执行。

强烈推荐新 PHP 库的作者使用此插件，他们欣赏静态类型的好处。

希望该项目能提高对 PHP 生态系统类型安全（或当前缺乏的类型安全）的认识。

虽然可能听起来很烦人，但维护者对下游项目中类型检查不足导致的支持问题做出反应的情况并不少见。除了这一点之外，通过更多地依赖静态类型而不是运行时检查，通过加强库的 API 边界，可以减少代码大小和维护负担。

安装

此包旨在作为 PHP 库 的依赖项安装。

在您的库中，将其添加到您的 composer.json

composer require roave/you-are-using-it-wrong

如果您的声明类型已经反映了您的库要求，则无需进一步更改即可开始使用该工具。

请注意，此工具不应在 "require-dev" 中使用，而应特别在 "require" 中使用，以便将类型检查应用于您的代码的下游消费者。

示例

您可以通过运行 cd examples && ./run-example.sh 来尝试以下示例。

假设您是 my/awesome-library 的作者，该库具有以下 composer.json

{
    "name": "my/awesome-library",
    "type": "library",
    "autoload": {
        "psr-4": {
            "My\\AwesomeLibrary\\": "src"
        }
    },
    "require": {
        "roave/you-are-using-it-wrong": "^1.0.0"
    }
}

假设以下 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) . '!';
    }
}

假设以下下游 a/project/composer.json 项目依赖于您的 my/awesome-library

{
    "name": "a/project",
    "type": "project",
    "autoload": {
        "psr-4": {
            "The\\Project\\": "src"
        }
    },
    "require": {
        "my/awesome-library": "^1.0.0"
    }
}

并且以下 a/project/src/MyExample.php

<?php declare(strict_types=1);

// notice the simple type error
echo \My\AwesomeLibrary\MyHelloWorld::sayHello([123, 456]);

然后该项目的 composer install 将失败

$ 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

解决方案

从类型检查的角度来看，此包设计得相当侵入性，但如果在安装/项目的根目录中检测到 psalm 配置，它将退出所有检查。在这种情况下，该工具假定项目的作者已经负责确保其自身域内的类型安全性，因此将退出而不执行进一步检查。

如上所述，该工具的设计围绕提高 PHP 生态系统中静态类型使用的认识，因此只有当它确信库的消费者自己处理了这个问题时，才会放弃。

专业支持

如果您需要帮助在项目中设置此库，您可以联系我们的咨询/支持团队 team@roave.com。