sci / assert
Extensible lightweight assertion library.
Requires
- php: >=5.4.0
Requires (Dev)
- humbug/humbug: ~1.0@dev
- phpunit/phpunit: ^4.7
- squizlabs/php_codesniffer: ^2.3
This package is auto-updated.
Last update: 2024-12-09 01:23:29 UTC
README
PHP library heavily inspired by beberlei/assert.
The purpose is a lightweight php library mainly for validating method parameters. The library's API is fluent DSL like.
Installation
Using composer:
composer require sci/assert dev-master
Motivation
Just as an example, php is not able to typehint array-ish arguments, i.e. array or \Traversable:
function foobar($values) { foreach ($values as $value) { // ... } } $a = array(1, 2, 3); $b = new \ArrayIterator($a); $c = 'not that iterable'; foobar($a); // fine foobar($b); // fine, too foobar($c); // Invalid argument supplied for foreach()
Ignoring this and relying on @param-Annotations (@param int[]
or @param array|\Traversable
) is quite bad.
Having an explicit guard is verbose and needs a separate unit test to achieve code coverage:
function foobar($values) { if (!is_array($values) && !$values instanceof \Traversable) { throw new \InvalidArgumentException(/* ... */); } // ... }
The solution may be this:
use Sci\Assert\Assert; function foobar($values) { Assert::that($values)->isTraversable(); // ... }
Examples
use Sci\Assert\Assert; // be it a string, matching a regular expression Assert::that($value)->isString()->machesRegExp('/[A-Z][a-z+]/'); // be it a collection of strings, matching a regular expression Assert::that($values)->all()->isString()->machesRegExp('/[A-Z][a-z+]/'); // be it a \DateTime and in year 2015 ('2015-01-01' <= $date < '2016-01-01') Assert::that($date) ->isInstanceOf('\DateTime') ->greaterThanOrEqual(new \DateTime('2015-01-01')) ->lessThan(new \DateTime('2016-01-01')); // ... or, in a different way: Assert::that($date) ->isInstanceOf('\DateTime') ->between(new \DateTime('2015-01-01 00:00:00'), new \DateTime('2015-12-31 23:59:59')); // be it a collection of \DateTime objects, each beeing in future Assert::that($dates)->all()->isInstanceOf('\DateTime')->greaterThan(new \DateTime('now')); // be it null, or a collection ... Assert::that($dates)->nullOr()->isInstanceOf('\DateTime');
Extending the library
The Assert library can be extended by subclassing. An example can be found here: NumberAssert
, which adds two changes to the Assert
base-class. First the Assert::equal()
base method is extendes by a delta/tolerance argument, when used with numeric values: NumberAssert::equal()
. Second, a prime number assertion is added: NumberAssert::prime()
.
use Sci\Assert\NumberAssert; NumberAssert::that(3.1415)->equal(M_PI, .001); NumberAssert::that(997)->prime();
or, for a better readability:
use Sci\Assert\NumberAssert as Assert; Assert::that(3.1415)->equal(M_PI, .001); Assert::that(997)->prime();
Complete assertion list
use Sci\Assert\Assert; // base assertions Assert::that($value)->isString(); Assert::that($value)->isInteger(); Assert::that($value)->isNumeric(); Assert::that($value)->isScalar(); Assert::that($value)->isResource(); Assert::that($value)->isTrue(); Assert::that($value)->isTraversable(); Assert::that($value)->isInstanceOf('\DateTime'); // comparison assertions Assert::that($value)->equal($valueRepeated); Assert::that($value)->strictEqual($valueRepeated); Assert::that($value)->lessThan(10); // Assert::that($value)->lt(10); Assert::that($value)->lessThanOrEqual(10); // Assert::that($value)->lte(10); Assert::that($value)->greaterThan(10); // Assert::that($value)->gt(10); Assert::that($value)->greaterThanOrEqual(10); // Assert::that($value)->gte(10); Assert::that($value)->between(10, 20); // same as Assert::that($value)->gte(10)->lte(20); Assert::that($value)->between('aaaa', 'bbbbb'); // string assertions Assert::that($value)->hasMinLength(8); Assert::that($value)->matches('/^[A-Z][a-z]+$/'); // meta assertions Assert::that($value)->all()->isString(); Assert::that($value)->nullOr()->isString();
use Sci\Assert\StringAssert; StringAssert::that($value)->isIpAddress(); StringAssert::that($value)->isIpAddress(FILTER_FLAG_IPV4); StringAssert::that($value)->isUrl(FILTER_FLAG_QUERY_REQUIRED | FILTER_FLAG_PATH_REQUIRED); StringAssert::that($value)->isEmail(); StringAssert::that($value)->isMac();
use Sci\Assert\FileSystemAssert; FileSystemAssert::that($filename)->exists(); FileSystemAssert::that($filename)->isFile(); FileSystemAssert::that($filename)->isDir(); FileSystemAssert::that($filename)->isLink();
Differences
While beberlei's fluent API is function-based (\Assert\that()
), the API of sci/assert uses a static method (Assert::that()
).
\Assert\that(1)->integer()->min(-10)->max(10);
use Sci\Assert\Assert; Assert::that(1)->isInteger()->greaterThanOrEqual(-10)->lessThanOrEqual(10); Assert::that(1)->isInteger()->gte(-10)->lte(10);
Although looking like an unimportant detail, the later solution is easier to extend by subclassing. See here.
License
All contents of this package are licensed under the MIT license.