diff options
Diffstat (limited to 'vendor/wikimedia/assert/src')
8 files changed, 408 insertions, 0 deletions
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 { + +} |