PHP Expect - Assertion Library for PHP
PHP Expect is a lightweight assertion library for PHP to validate arguments and invariants., (*1)
Installation
You can use Composer to download and install PHP Expect.
To add PHP Expect to your project, simply add a dependency on nunzion/php-expect to your project's composer.json file., (*2)
Here is a minimal example of a composer.json file that just defines a dependency on PHP Expect:, (*3)
``` json
{
"require": {
"nunzion/php-expect": "~1.0"
}
}, (*4)
Usage
-----
For larger projects the `Expect` class should be derived to keep dependencies to `Nunzion\Expect` in one place:
``` php
<?php
namespace MyCompany\MyApplication;
class Expect extends \Nunzion\Expect
{
//If you need custom validations, you can define them here.
}
//Later you can call:
\MyCompany\MyApplication\Expect::that(3)->isBetween(1, 4);
//Instead of \Nunzion\Expect::that(3)->isBetween(1, 4);
Supported Tests
``` php
<?php, (*5)
use MyCompany\MyApplication\Expect;, (*6)
Expect::that(null)->isNull();
Expect::that(0)->isNotNull(); // 0 !== null, so 0 is not null.
Expect::that("")->isEmpty();
Expect::that(2)->isNotEmpty();, (*7)
Expect::that("foo")->equals("foo"); //"foo" == "foo"
Expect::that(1)->isTheSameAs(1); //1 === 1, (*8)
Expect::that("bar")->isString();
Expect::that(4)->isInt();
Expect::that(new Foo())->isObject();
Expect::that("file_exists")->isCallable();
Expect::that(array(1, 2))->isArray();
Expect::that($a)->isTypeOf("\FooInterface");, (*9)
//Chaining is possible too
Expect::that(1)->isBetween(0, 2)
->isGreaterThan(0)
->isLessThan(2)
->isGreaterThanOrEqualTo(1)
->isLessThanOrEqualTo(1);, (*10)
$arr = array("bla" => 2, "foo" => null);
Expect::that($arr)->itsArrayElement("bla")->isDefined();
Expect::that($arr)->itsArrayElement("bla")->isInt();
Expect::that($arr)->itsArrayElement("blubb")->isUndefinedOrInt();
Expect::that($arr)->itsArrayElement("foo")->isNullOrInt();, (*11)
$result = myTest($a); //Some custom test.
if ($result != null)
{
//Will throw an \UnexpectedValueException with message:
//"The value must be valid, the test returned: " + $result.
Expect::that(null)->_("must be valid, the test returned: {testResult}",
array("testResult" => $result));
//The value for the placeholder 'testResult' will be available within
//the exception and could be used by loggers.
}, (*12)
### Code Example
``` php
<?php
use Nunzion\Expect;
class Square
{
private $a;
private $b;
public function __construct($length)
{
//throws \InvalidArgumentException,
//because "length" is a parameter of Square::__construct
Expect::that($length)->isGreaterThan(0);
$this->a = $length;
$this->b = $length;
}
public function getArea()
{
//throws Nunzion\InvariantException,
//because "b" is a member of Square
Expect::that($this->b)->equals($this->a);
return $this->a * $this->b;
}
public function setData($data)
{
//Expects data is array and has a key 'length'
//which is int and greater than 0
Expect::that($data)->itsArrayElement("length")->isGreaterThan(0);
$this->a = $data["length"];
$this->b = $this->a;
}
}
new Square(-1);
Preconditions, Invariants and Normal Conditions
PHP Expect distinguishes between preconditions, invariants and normal conditions., (*13)
Preconditions validate arguments - invalid arguments can be caused by bugs inside the callers code or by bad user input.
If a condition fails and the value to check was a parameter (the expression inside that()), PHP Expect automatically throws an \InvalidArgumentException., (*14)
Invariants are conditions which ensure that the state of an object is always valid.
PHP Expect identifies such conditions if the value to check is a member of $this and throws a Nunzion\InvariantViolationException if the condition fails.
Usually bugs cause violated invariants, so these exceptions should be logged., (*15)
Normal conditions are all conditions which PHP Expect does not recognize., (*16)
isNullOr and isUndefinedOr
You can prepend each is* method call with isNullOr and isUndefinedOr. The test will then succeed if the value to test is either null or undefined., (*17)
Extending Nunzion\Expect
You can extend Nunzion\Expect to customize the exceptions to throw. This can be done by overwriting the get*ExceptionConstructor methods:, (*18)
``` php
<?php, (*19)
namespace MyCompany;, (*20)
class Expect extends Nunzion\Expect
{
protected function getPreconditionViolationExceptionConstructor(
$message, $arguments)
{
print_r($arguments); //arguments contains additional information
//Return the exception construct information you want to throw instead.
//Delaying the construction of the exception will prevent its stack trace
//to contain too much PHP Expect methods.
return array(
//the method which will be called to create the exception.
array(new \ReflectionClass(
"\MyNamespace\MyInvariantViolationException"), "newInstance"),
//the arguments which will be passed to the method.
array($message)
);
}, (*21)
protected function getInvariantViolationExceptionConstructor(
$message, $arguments)
{
print_r($arguments);
return parent::getInvariantViolationExceptionConstructor(
$message, $arguments);
}
protected function getConditionViolationExceptionConstructor(
$message, $arguments)
{
print_r($arguments);
return parent::getConditionViolationExceptionConstructor(
$message, $arguments);
}
}, (*22)
```, (*23)
Author
Henning Dieterichs - henning.dieterichs@hediet.de, (*24)
License
PHP Expect is licensed under the MIT License., (*25)
Wallogit.com
