diff options
Diffstat (limited to 'vendor/wikimedia/assert')
| -rw-r--r-- | vendor/wikimedia/assert/COPYING | 21 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/README.md | 43 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/composer.json | 24 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/phpunit.xml.dist | 27 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/Assert.php | 204 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/AssertionException.php | 16 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/InvariantException.php | 18 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/ParameterAssertionException.php | 49 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/ParameterElementTypeException.php | 43 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/ParameterTypeException.php | 43 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/PostconditionException.php | 18 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/src/PreconditionException.php | 17 | ||||
| -rw-r--r-- | vendor/wikimedia/assert/tests/phpunit/AssertTest.php | 156 |
13 files changed, 679 insertions, 0 deletions
diff --git a/vendor/wikimedia/assert/COPYING b/vendor/wikimedia/assert/COPYING new file mode 100644 index 00000000..56f0386f --- /dev/null +++ b/vendor/wikimedia/assert/COPYING @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2014 Wikimedia Deutschland e.V. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/vendor/wikimedia/assert/README.md b/vendor/wikimedia/assert/README.md new file mode 100644 index 00000000..6fa9b4d2 --- /dev/null +++ b/vendor/wikimedia/assert/README.md @@ -0,0 +1,43 @@ +This package provides an alternative to PHP's `assert()` that allows for an simple and reliable way +to check preconditions and postconditions in PHP code. It was proposed [as a MediaWiki RFC](https://www.mediawiki.org/wiki/Requests_for_comment/Assert), +but is completely generic and can be used by any PHP program or library. It is published under the +MIT license, see the COPYING file. + +Usage +------- + +The Assert class provides several static methods for checking various kinds of assertions. +The most common kind is to check the type of a parameter, typically in a constructor or a +setter method: + + function setFoo( $foo ) { + Assert::parameterType( 'integer', $foo, 'foo' ); + Assert::parameter( $foo > 0, 'foo', 'must be greater than 0' ); + } + + function __construct( $bar, array $bazz ) { + Assert::parameterType( 'Me\MyApp\SomeClass', $bar ); + Assert::parameterElementType( 'int', $bazz ); + } + +Checking parameters, or other assertions such as pre- or postconditions, is not recommended for +performance critical regions of the code, since evaluating expressions and calling the assertion +functions costs time. + + +Rationale +----------- +The background of this proposal is the recurring discussions about whether PHP's `assert()` +can and should be used in MediaWiki code. Two relevant threads: +* [Using PHP's assert in MediaWiki code](http://www.gossamer-threads.com/lists/wiki/wikitech/275737) +* [Is assert() allowed?](http://www.gossamer-threads.com/lists/wiki/wikitech/378676) + +The outcome appears to be that +* assertions are generally a good way to improve code quality +* but PHP's ''assert()'' is broken by design + +Following a [suggestion by Tim Starling](http://www.gossamer-threads.com/lists/wiki/wikitech/378815#378815), +this package provides an alternative to PHP's built in `assert()`. + +[](https://travis-ci.org/wmde/Assert) +[](https://scrutinizer-ci.com/g/wmde/Assert/?branch=master) diff --git a/vendor/wikimedia/assert/composer.json b/vendor/wikimedia/assert/composer.json new file mode 100644 index 00000000..121f7162 --- /dev/null +++ b/vendor/wikimedia/assert/composer.json @@ -0,0 +1,24 @@ +{ + "name": "wikimedia/assert", + "description": "Provides runtime assertions", + "keywords": ["PHP", "QA", "assert", "assertions", "precondition", "postcondition"], + "homepage": "https://github.com/wmde/Assert", + "license": "MIT", + "authors": [ + { + "name": "Daniel Kinzler" + } + ], + + "require-dev": { + "phpunit/phpunit": "3.7.*" + }, + + "autoload": { + "psr-4": { + "Wikimedia\\Assert\\": "src/", + "Wikimedia\\Assert\\Test\\": "tests/phpunit/" + } + } + +} diff --git a/vendor/wikimedia/assert/phpunit.xml.dist b/vendor/wikimedia/assert/phpunit.xml.dist new file mode 100644 index 00000000..49a2f87d --- /dev/null +++ b/vendor/wikimedia/assert/phpunit.xml.dist @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="utf-8" ?> +<phpunit bootstrap="./vendor/autoload.php" + backupGlobals="false" + backupStaticAttributes="false" + cacheTokens="false" + colors="true" + convertErrorsToExceptions="true" + convertNoticesToExceptions="true" + convertWarningsToExceptions="true" + stopOnError="false" + stopOnFailure="false" + stopOnIncomplete="false" + stopOnSkipped="false" + verbose="true"> + + <testsuites> + <testsuite name="Assert"> + <directory>./tests/phpunit</directory> + </testsuite> + </testsuites> + <filter> + <whitelist addUncoveredFilesFromWhitelist="true"> + <directory suffix=".php">src</directory> + </whitelist> + </filter> + +</phpunit>
\ No newline at end of file diff --git a/vendor/wikimedia/assert/src/Assert.php b/vendor/wikimedia/assert/src/Assert.php new file mode 100644 index 00000000..53b438a5 --- /dev/null +++ b/vendor/wikimedia/assert/src/Assert.php @@ -0,0 +1,204 @@ +<?php + +namespace Wikimedia\Assert; + +/** + * Assert provides functions for assorting preconditions (such as parameter types) and + * postconditions. It is intended as a safer alternative to PHP's assert() function. + * + * Note that assertions evaluate expressions and add function calls, so using assertions + * may have a negative impact on performance when used in performance hotspots. The idea + * if this class is to have a neat tool for assertions if and when they are needed. + * It is not recommended to place assertions all over the code indiscriminately. + * + * For more information, see the the README file. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class Assert { + + /** + * Checks a precondition, that is, throws a PreconditionException if $condition is false. + * For checking call parameters, use Assert::parameter() instead. + * + * This is provided for completeness, most preconditions should be covered by + * Assert::parameter() and related assertions. + * + * @see parameter() + * + * @note This is intended mostly for checking preconditions in constructors and setters, + * or before using parameters in complex computations. + * Checking preconditions in every function call is not recommended, since it may have a + * negative impact on performance. + * + * @param bool $condition + * @param string $description The message to include in the exception if the condition fails. + * + * @throws PreconditionException if $condition is not true. + */ + public static function precondition( $condition, $description ) { + if ( !$condition ) { + throw new PreconditionException( "Precondition failed: $description" ); + } + } + + /** + * Checks a parameter, that is, throws a ParameterAssertionException if $condition is false. + * This is similar to Assert::precondition(). + * + * @note This is intended for checking parameters in constructors and setters. + * Checking parameters in every function call is not recommended, since it may have a + * negative impact on performance. + * + * @param bool $condition + * @param string $name The name of the parameter that was checked. + * @param string $description The message to include in the exception if the condition fails. + * + * @throws ParameterAssertionException if $condition is not true. + */ + public static function parameter( $condition, $name, $description ) { + if ( !$condition ) { + throw new ParameterAssertionException( $name, $description ); + } + } + + /** + * Checks an parameter's type, that is, throws a InvalidArgumentException if $condition is false. + * This is really a special case of Assert::precondition(). + * + * @note This is intended for checking parameters in constructors and setters. + * Checking parameters in every function call is not recommended, since it may have a + * negative impact on performance. + * + * @note If possible, type hints should be used instead of calling this function. + * It is intended for cases where type hints to not work, e.g. for checking primitive types. + * + * @param string $type The parameter's expected type. Can be the name of a native type or a + * class or interface. If multiple types are allowed, they can be given separated by + * a pipe character ("|"). + * @param mixed $value The parameter's actual value. + * @param string $name The name of the parameter that was checked. + * + * @throws ParameterTypeException if $value is not of type (or, for objects, is not an + * instance of) $type. + */ + public static function parameterType( $type, $value, $name ) { + if ( !self::hasType( $value, explode( '|', $type ) ) ) { + throw new ParameterTypeException( $name, $type ); + } + } + + /** + * Checks the type of all elements of an parameter, assuming the parameter is an array, + * that is, throws a ParameterElementTypeException if $value + * + * @note This is intended for checking parameters in constructors and setters. + * Checking parameters in every function call is not recommended, since it may have a + * negative impact on performance. + * + * @param string $type The elements' expected type. Can be the name of a native type or a + * class or interface. If multiple types are allowed, they can be given separated by + * a pipe character ("|"). + * @param mixed $value The parameter's actual value. If this is not an array, + * a ParameterTypeException is raised. + * @param string $name The name of the parameter that was checked. + * + * @throws ParameterTypeException If $value is not an array. + * @throws ParameterElementTypeException If an element of $value is not of type + * (or, for objects, is not an instance of) $type. + */ + public static function parameterElementType( $type, $value, $name ) { + self::parameterType( 'array', $value, $name ); + + $allowedTypes = explode( '|', $type ); + + foreach ( $value as $element ) { + if ( !self::hasType( $element, $allowedTypes ) ) { + throw new ParameterElementTypeException( $name, $type ); + } + } + } + + /** + * Checks a postcondition, that is, throws a PostconditionException if $condition is false. + * This is very similar Assert::invariant() but is intended for use only after a computation + * is complete. + * + * @note This is intended for sanity-checks in the implementation of complex algorithms. + * Note however that it should not be used in performance hotspots, since evaluating + * $condition and calling postcondition() costs time. + * + * @param bool $condition + * @param string $description The message to include in the exception if the condition fails. + * + * @throws PostconditionException + */ + public static function postcondition( $condition, $description ) { + if ( !$condition ) { + throw new PostconditionException( "Postcondition failed: $description" ); + } + } + + /** + * Checks an invariant, that is, throws a InvariantException if $condition is false. + * This is very similar Assert::postcondition() but is intended for use throughout the code. + * + * @note This is intended for sanity-checks in the implementation of complex algorithms. + * Note however that it should not be used in performance hotspots, since evaluating + * $condition and calling postcondition() costs time. + * + * @param bool $condition + * @param string $description The message to include in the exception if the condition fails. + * + * @throws InvariantException + */ + public static function invariant( $condition, $description ) { + if ( !$condition ) { + throw new InvariantException( "Invariant failed: $description" ); + } + } + + /** + * @param mixed $value + * @param array $allowedTypes + * + * @return bool + */ + private static function hasType( $value, array $allowedTypes ) { + // Apply strtolower because gettype returns "NULL" for null values. + $type = strtolower( gettype( $value ) ); + + if ( in_array( $type, $allowedTypes ) ) { + return true; + } + + if ( is_callable( $value ) && in_array( 'callable', $allowedTypes ) ) { + return true; + } + + if ( is_object( $value ) && self::isInstanceOf( $value, $allowedTypes ) ) { + return true; + } + + return false; + } + + /** + * @param mixed $value + * @param array $allowedTypes + * + * @return bool + */ + private static function isInstanceOf( $value, array $allowedTypes ) { + foreach ( $allowedTypes as $type ) { + if ( $value instanceof $type ) { + return true; + } + } + + return false; + } + +} diff --git a/vendor/wikimedia/assert/src/AssertionException.php b/vendor/wikimedia/assert/src/AssertionException.php new file mode 100644 index 00000000..488c3135 --- /dev/null +++ b/vendor/wikimedia/assert/src/AssertionException.php @@ -0,0 +1,16 @@ +<?php + +namespace Wikimedia\Assert; + +/** + * Marker interface for exceptions thrown by Assert. Since the exceptions thrown by Assert + * use different standard exceptions as base classes, the marker interface is needed to be + * able to catch them all at once. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +interface AssertionException { + +} diff --git a/vendor/wikimedia/assert/src/InvariantException.php b/vendor/wikimedia/assert/src/InvariantException.php new file mode 100644 index 00000000..870ce1a0 --- /dev/null +++ b/vendor/wikimedia/assert/src/InvariantException.php @@ -0,0 +1,18 @@ +<?php + +namespace Wikimedia\Assert; + +use LogicException; + +/** + * Exception indicating that an invariant assertion failed. + * This generally means an error in the internal logic of a function, or a serious problem + * in the runtime environment. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class InvariantException extends LogicException implements AssertionException { + +} diff --git a/vendor/wikimedia/assert/src/ParameterAssertionException.php b/vendor/wikimedia/assert/src/ParameterAssertionException.php new file mode 100644 index 00000000..cb42cc6f --- /dev/null +++ b/vendor/wikimedia/assert/src/ParameterAssertionException.php @@ -0,0 +1,49 @@ +<?php + +namespace Wikimedia\Assert; + +use InvalidArgumentException; + +/** + * Exception indicating that an parameter assertion failed. + * This generally means a disagreement between the caller and the implementation of a function. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class ParameterAssertionException extends InvalidArgumentException implements AssertionException { + + /** + * @var string + */ + private $parameterName; + + /** + * @param string $parameterName + * @param string $description + * + * @throws ParameterTypeException + */ + public function __construct( $parameterName, $description ) { + if ( !is_string( $parameterName ) ) { + throw new ParameterTypeException( 'parameterName', 'string' ); + } + + if ( !is_string( $description ) ) { + throw new ParameterTypeException( 'description', 'string' ); + } + + parent::__construct( "Bad value for parameter $parameterName: $description" ); + + $this->parameterName = $parameterName; + } + + /** + * @return string + */ + public function getParameterName() { + return $this->parameterName; + } + +} diff --git a/vendor/wikimedia/assert/src/ParameterElementTypeException.php b/vendor/wikimedia/assert/src/ParameterElementTypeException.php new file mode 100644 index 00000000..eaaa663f --- /dev/null +++ b/vendor/wikimedia/assert/src/ParameterElementTypeException.php @@ -0,0 +1,43 @@ +<?php + +namespace Wikimedia\Assert; + +/** + * Exception indicating that a parameter element type assertion failed. + * This generally means a disagreement between the caller and the implementation of a function. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class ParameterElementTypeException extends ParameterAssertionException { + + /** + * @var string + */ + private $elementType; + + /** + * @param string $parameterName + * @param string $elementType + * + * @throws ParameterTypeException + */ + public function __construct( $parameterName, $elementType ) { + if ( !is_string( $elementType ) ) { + throw new ParameterTypeException( 'elementType', 'string' ); + } + + parent::__construct( $parameterName, "all elements must be $elementType" ); + + $this->elementType = $elementType; + } + + /** + * @return string + */ + public function getElementType() { + return $this->elementType; + } + +} diff --git a/vendor/wikimedia/assert/src/ParameterTypeException.php b/vendor/wikimedia/assert/src/ParameterTypeException.php new file mode 100644 index 00000000..943f6c08 --- /dev/null +++ b/vendor/wikimedia/assert/src/ParameterTypeException.php @@ -0,0 +1,43 @@ +<?php + +namespace Wikimedia\Assert; + +/** + * Exception indicating that a parameter type assertion failed. + * This generally means a disagreement between the caller and the implementation of a function. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class ParameterTypeException extends ParameterAssertionException { + + /** + * @var string + */ + private $parameterType; + + /** + * @param string $parameterName + * @param string $parameterType + * + * @throws ParameterTypeException + */ + public function __construct( $parameterName, $parameterType ) { + if ( !is_string( $parameterType ) ) { + throw new ParameterTypeException( 'parameterType', 'string' ); + } + + parent::__construct( $parameterName, "must be a $parameterType" ); + + $this->parameterType = $parameterType; + } + + /** + * @return string + */ + public function getParameterType() { + return $this->parameterType; + } + +} diff --git a/vendor/wikimedia/assert/src/PostconditionException.php b/vendor/wikimedia/assert/src/PostconditionException.php new file mode 100644 index 00000000..a7753ef0 --- /dev/null +++ b/vendor/wikimedia/assert/src/PostconditionException.php @@ -0,0 +1,18 @@ +<?php + +namespace Wikimedia\Assert; + +use LogicException; + +/** + * Exception indicating that a postcondition assertion failed. + * This generally means an error in the internal logic of a function, or a serious problem + * in the runtime environment. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class PostconditionException extends LogicException implements AssertionException { + +} diff --git a/vendor/wikimedia/assert/src/PreconditionException.php b/vendor/wikimedia/assert/src/PreconditionException.php new file mode 100644 index 00000000..97e98035 --- /dev/null +++ b/vendor/wikimedia/assert/src/PreconditionException.php @@ -0,0 +1,17 @@ +<?php + +namespace Wikimedia\Assert; + +use RuntimeException; + +/** + * Exception indicating that an precondition assertion failed. + * This generally means a disagreement between the caller and the implementation of a function. + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ +class PreconditionException extends RuntimeException implements AssertionException { + +} diff --git a/vendor/wikimedia/assert/tests/phpunit/AssertTest.php b/vendor/wikimedia/assert/tests/phpunit/AssertTest.php new file mode 100644 index 00000000..038bc1c1 --- /dev/null +++ b/vendor/wikimedia/assert/tests/phpunit/AssertTest.php @@ -0,0 +1,156 @@ +<?php + +namespace Wikimedia\Assert\Test; + +use LogicException; +use PHPUnit_Framework_TestCase; +use RuntimeException; +use Wikimedia\Assert\Assert; +use Wikimedia\Assert\AssertionException; +use Wikimedia\Assert\ParameterAssertionException; +use Wikimedia\Assert\ParameterElementTypeException; +use Wikimedia\Assert\ParameterTypeException; + +/** + * @covers Wikimedia\Assert\Assert + * + * @license MIT + * @author Daniel Kinzler + * @copyright Wikimedia Deutschland e.V. + */ + +class AssertTest extends PHPUnit_Framework_TestCase { + + public function testPrecondition_pass() { + Assert::precondition( true, 'test' ); + } + + public function testPrecondition_fail() { + $this->setExpectedException( 'Wikimedia\Assert\PreconditionException' ); + Assert::precondition( false, 'test' ); + } + + public function testParameter_pass() { + Assert::parameter( true, 'foo', 'test' ); + } + + public function testParameter_fail() { + try { + Assert::parameter( false, 'test', 'testing' ); + } catch ( ParameterAssertionException $ex ) { + $this->assertEquals( 'test', $ex->getParameterName() ); + } + } + + public function validParameterTypeProvider() { + return array( + 'simple' => array( 'string', 'hello' ), + 'class' => array( 'RuntimeException', new RuntimeException() ), + 'multi' => array( 'string|array|Closure', function() {} ), + 'null' => array( 'integer|null', null ), + 'callable' => array( 'null|callable', 'time' ), + ); + } + + /** + * @dataProvider validParameterTypeProvider + */ + public function testParameterType_pass( $type, $value ) { + Assert::parameterType( $type, $value, 'test' ); + } + + public function invalidParameterTypeProvider() { + return array( + 'simple' => array( 'string', 5 ), + 'class' => array( 'RuntimeException', new LogicException() ), + 'multi' => array( 'string|integer|Closure', array() ), + 'null' => array( 'integer|string', null ), + 'callable' => array( 'null|callable', array() ), + ); + } + + /** + * @dataProvider invalidParameterTypeProvider + */ + public function testParameterType_fail( $type, $value ) { + try { + Assert::parameterType( $type, $value, 'test' ); + $this->fail( 'Expected ParameterTypeException' ); + } catch ( ParameterTypeException $ex ) { + $this->assertEquals( $type, $ex->getParameterType() ); + $this->assertEquals( 'test', $ex->getParameterName() ); + } + } + + public function testParameterType_catch() { + try { + Assert::parameterType( 'string', 17, 'test' ); + $this->fail( 'Expected exception' ); + } catch ( AssertionException $ex ) { + // ok + } + } + + public function validParameterElementTypeProvider() { + return array( + 'empty' => array( 'string', array() ), + 'simple' => array( 'string', array( 'hello', 'world' ) ), + 'class' => array( 'RuntimeException', array( new RuntimeException() ) ), + 'multi' => array( 'string|array|Closure', array( array(), function() {} ) ), + 'null' => array( 'integer|null', array( null, 3, null ) ), + ); + } + + /** + * @dataProvider validParameterElementTypeProvider + */ + public function testParameterElementType_pass( $type, $value ) { + Assert::parameterElementType( $type, $value, 'test' ); + } + + public function invalidParameterElementTypeProvider() { + return array( + 'simple' => array( 'string', array( 'hello', 5 ) ), + 'class' => array( 'RuntimeException', array( new LogicException() ) ), + 'multi' => array( 'string|array|Closure', array( array(), function() {}, 5 ) ), + 'null' => array( 'integer|string', array( null, 3, null ) ), + ); + } + + /** + * @dataProvider invalidParameterElementTypeProvider + */ + public function testParameterElementType_fail( $type, $value ) { + try { + Assert::parameterElementType( $type, $value, 'test' ); + $this->fail( 'Expected ParameterElementTypeException' ); + } catch ( ParameterElementTypeException $ex ) { + $this->assertEquals( $type, $ex->getElementType() ); + $this->assertEquals( 'test', $ex->getParameterName() ); + } + } + + public function testParameterElementType_bad() { + $this->setExpectedException( 'Wikimedia\Assert\ParameterTypeException' ); + Assert::parameterElementType( 'string', 'foo', 'test' ); + } + + public function testInvariant_pass() { + Assert::invariant( true, 'test' ); + } + + public function testInvariant_fail() { + $this->setExpectedException( 'Wikimedia\Assert\InvariantException' ); + Assert::invariant( false, 'test' ); + } + + public function testPostcondition_pass() { + Assert::postcondition( true, 'test' ); + } + + public function testPostcondition_fail() { + $this->setExpectedException( 'Wikimedia\Assert\PostconditionException' ); + Assert::postcondition( false, 'test' ); + } + +} |