roave/strict-php

This package is abandoned and no longer maintained. No replacement package was suggested.

A strict runtime type and invariant checker for developing safer PHP applications

dev-master / 1.0.x-dev 2015-10-27 07:06 UTC

Requires

• php: ~5.6|~7.0
• goaop/framework: ~1.0.0@ALPHA
• internations/type-jail: 0.4.*
• phpdocumentor/reflection-docblock: ~2.0
• phpdocumentor/type-resolver: ^0.1.5

Requires (Dev)

• couscous/couscous: dev-master
• phpunit/phpunit: ~4.7

MIT

• Marco Pivetta
• Jefersson Nathan

• php
• development
• continuous integration
• analysis
• strict
• type safety

README

StrictPhp is a development tool aimed at bringing stricter runtime assertions into PHP applications and libraries.

Authors

• Marco Pivetta
• Jefersson Nathan

Installation

$ composer require roave/strict-php

Please note that the current version has unstable dependencies.

In order to install those dependencies, you can set "minimum-stability" in your composer.json:

{
    "minimum-stability": "dev"
}

Usage

After installing StrictPhp, point it at the directory to be checked at runtime (the code that you are writing) via following code:

\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 will then intercept any runtime operations that are considered "illegal" and throw an exception or a catchable fatal error.

Please remember to execute this code before any code that may autoload any of the classes that should be checked.

Configuration

The StrictPhp\StrictPhpKernel can be initialized with a set of options to be passed to go-aop-php and a set of feature flags:

• 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

Each of these features are described below.

Features

StrictPhp currently supports following features:

Per-property type checks

Enabled via flag StrictPhp\StrictPhpKernel::CHECK_PROPERTY_WRITE_TYPE.

This feature will prevent your application from assigning illegal values to properties that are type-hinted (via docblock) differently. As an example, consider following class:

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

Following code will work:

$object = new Example();

$object->integer = 123;

Following code will crash:

$object = new Example();

$object->integer = '123';

Please note that this kind of feature currently only works with public and protected properties.

Return type checks

Quite similar to the above functionality, this feature will prevent your application from returning illegal values from methods that are type-hinted (via docblock) differently. As an example, consider following method:

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

Following code will work:

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

Following code will crash:

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

Please note that this kind of feature currently only works with public and protected methods.

immutable properties

Enabled via flag StrictPhp\StrictPhpKernel::CHECK_PROPERTY_WRITE_IMMUTABILITY.

This feature will prevent your application from overwriting object properties that are marked as @immutable. As an example, consider following class:

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

Following code will crash:

$object = new Example();

$object->immutableProperty = 'a value';

echo 'Works till here!';

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

Please note that this kind of feature currently only works with public and protected properties.

Public constructor property initialization checks

Enabled via flag StrictPhp\StrictPhpKernel::CHECK_STATE_AFTER_CONSTRUCTOR_CALL.

This feature of StrictPhp allows checking whether a public constructor of a class fully initialized an object.

Following code will make StrictPhp crash your application:

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

    public function __construct()
    {
    }
}

In order to make this code work, you have to either annotate $arrayProperty with @var array|null, or make the constructor initialize the property correctly:

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

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

Parameter interface jailing

Enabled via flag StrictPhp\StrictPhpKernel::JAIL_PUBLIC_METHOD_PARAMETERS.

This feature of StrictPhp "jails" (restricts) calls to non-interfaced methods whenever an interface is used as a type-hint.

Following example will work, but will crash if StrictPhp is enabled:

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

This prevents consumers of your APIs to design their code against non-API methods.

Parameter checking

Enabled via flag StrictPhp\StrictPhpKernel::CHECK_PUBLIC_METHOD_PARAMETER_TYPE.

StrictPhp also provides a way to check parameters types in more detail during public method calls.

Specifically, the following code will work in PHP:

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

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

This code will crash in StrictPhp due to the type mismatch in $lineItems (which should be a collection of LineItem objects instead).

Current limitations

This package uses voodoo magic to operate, specifically go-aop-php.

Go AOP PHP has some limitations when it comes to intercepting access to private class members, so please be aware that it has limited scope (for now).

This package only works against autoloaded classes; classes that aren't handled by an autoloader cannot be rectified by StrictPhp.

License

This package is released under the MIT license.

Contributing

If you wish to contribute to the project, please read the CONTRIBUTING notes.