README

StrictPhp 是一个开发工具，旨在将更严格的运行时断言引入PHP应用程序和库。

作者

• Marco Pivetta
• Jefersson Nathan

安装

$ composer require roave/strict-php

请注意，当前版本有不稳定依赖。

为了安装这些依赖项，您可以在您的 composer.json 中设置 "minimum-stability"

{
    "minimum-stability": "dev"
}

使用

安装 StrictPhp 后，通过以下代码将其指向要检查的目录（您正在编写的代码）

\StrictPhp\StrictPhpKernel::bootstrap([
    'debug'        => true,
    // change this if you use this tool on multiple projects:
    'cacheDir'     => sys_get_temp_dir(),
    'includePaths' => [
        __DIR__ . '/path/to/your/sources',
    ],
]);

StrictPhp 将拦截任何被认为是“非法”的运行时操作，并抛出异常或可捕获的致命错误。

请记住在执行此代码之前执行任何可能自动加载应进行检查的类的代码。

配置

可以使用要传递给 go-aop-php 的选项集和一组功能标志来初始化 StrictPhp\StrictPhpKernel

• StrictPhp\StrictPhpKernel::CHECK_STATE_AFTER_CONSTRUCTOR_CALL
• StrictPhp\StrictPhpKernel::JAIL_PUBLIC_METHOD_PARAMETERS
• StrictPhp\StrictPhpKernel::CHECK_STATE_AFTER_PUBLIC_METHOD_CALL
• StrictPhp\StrictPhpKernel::CHECK_PUBLIC_METHOD_PARAMETER_TYPE
• StrictPhp\StrictPhpKernel::CHECK_PUBLIC_METHOD_RETURN_TYPE
• StrictPhp\StrictPhpKernel::CHECK_PROPERTY_WRITE_IMMUTABILITY
• StrictPhp\StrictPhpKernel::CHECK_PROPERTY_WRITE_TYPE

以下将详细描述每个功能。

功能

StrictPhp 目前支持以下功能

按属性类型检查

通过标志 StrictPhp\StrictPhpKernel::CHECK_PROPERTY_WRITE_TYPE 启用。

此功能将防止您的应用程序将非法值分配给类型提示（通过 docblock）不同的属性。例如，考虑以下类

class Example
{
    /**
     * @var int|null
     */
    public $integer;
}

以下代码将工作

$object = new Example();

$object->integer = 123;

以下代码将崩溃

$object = new Example();

$object->integer = '123';

请注意，此类功能目前仅适用于公共和受保护属性。

返回类型检查

与上述功能相当，此功能将防止您的应用程序从类型提示（通过 docblock）不同的方法返回非法值。例如，考虑以下方法

class Example
{
    /**
     * @return string
     */
    public function dummyReturn($value)
    {
        return $value;
    }
}

以下代码将工作

(new Example())->dummyReturn('string');

以下代码将崩溃

(new Example())->dummyReturn(123);

请注意，此类功能目前仅适用于公共和受保护方法。

不可变属性

通过标志 StrictPhp\StrictPhpKernel::CHECK_PROPERTY_WRITE_IMMUTABILITY 启用。

此功能将防止您的应用程序覆盖标记为 @immutable 的对象属性。例如，考虑以下类

class Example
{
    /**
     * @immutable
     */
    public $immutableProperty;
}

以下代码将崩溃

$object = new Example();

$object->immutableProperty = 'a value';

echo 'Works till here!';

$object->immutableProperty = 'another value'; // crash

请注意，此类功能目前仅适用于公共和受保护属性。

公共构造函数属性初始化检查

通过标志 StrictPhp\StrictPhpKernel::CHECK_STATE_AFTER_CONSTRUCTOR_CALL 启用。

StrictPhp的这个功能允许检查一个类的公共构造函数是否完全初始化了一个对象。

以下代码会导致StrictPhp使您的应用程序崩溃

class Example
{
    /**
     * @var array
     */
    private $arrayProperty;

    public function __construct()
    {
    }
}

为了使此代码正常工作，您必须对$arrayProperty进行注解@var array|null，或者使构造函数正确初始化属性

class Example
{
    /**
     * @var array
     */
    private $arrayProperty;

    public function __construct()
    {
        $this->arrayProperty = ['initial status'];
    }
}

参数接口监禁

通过标志StrictPhp\StrictPhpKernel::JAIL_PUBLIC_METHOD_PARAMETERS启用。

StrictPhp的这个功能会在使用接口作为类型提示时“监禁”（限制）对非接口方法的调用。

以下示例将正常工作，但如果启用StrictPhp则会导致崩溃

interface HornInterface
{
    public function honk();
}

class TheUsualHorn implements HornInterface
{
    public function honk() { var_dump('honk'); }
    public function sadTrombone() { var_dump('pooapooapooapoaaaa'); }
}

class Car
{
    public function honk(HornInterface $horn, $sad = false)
    {
        if ($sad) {
            // method not covered by interface: crash
            $horn->sadTrombone();

            return;
        }

        // interface respected
        $horn->honk();
    }
}

$car  = new Car();
$horn = new TheUsualHorn();

$car->honk($horn, false); // works
$car->honk($horn, true); // crashes

这可以防止API的消费者针对非API方法设计其代码。

参数检查

通过标志StrictPhp\StrictPhpKernel::CHECK_PUBLIC_METHOD_PARAMETER_TYPE启用。

StrictPhp还提供了一种方式，在公共方法调用期间更详细地检查参数类型。

具体来说，以下代码在PHP中将正常工作

final class Invoice
{
    /**
     * @param LineItem[] $lineItems
     */
    public function __construct(array $lineItems)
    {
        // ...
    }
}

$invoice = new Invoice(['foo', 'bar']);

此代码将在StrictPhp中由于$lineItems（应为LineItem对象集合）的类型不匹配而崩溃。

当前限制

此包使用voodoo魔法来操作，具体为go-aop-php。

Go AOP PHP在拦截对私有类成员的访问时有一些限制，因此请注意，其作用域有限（目前如此）。

此包仅针对自动加载的类工作；未经自动加载器处理的类无法由StrictPhp修正。

许可协议

此包在MIT许可协议下发布。

贡献

如果您想为此项目做出贡献，请阅读CONTRIBUTING说明。