summaryrefslogtreecommitdiff
path: root/vendor/wikimedia/assert/src
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/wikimedia/assert/src')
-rw-r--r--vendor/wikimedia/assert/src/Assert.php204
-rw-r--r--vendor/wikimedia/assert/src/AssertionException.php16
-rw-r--r--vendor/wikimedia/assert/src/InvariantException.php18
-rw-r--r--vendor/wikimedia/assert/src/ParameterAssertionException.php49
-rw-r--r--vendor/wikimedia/assert/src/ParameterElementTypeException.php43
-rw-r--r--vendor/wikimedia/assert/src/ParameterTypeException.php43
-rw-r--r--vendor/wikimedia/assert/src/PostconditionException.php18
-rw-r--r--vendor/wikimedia/assert/src/PreconditionException.php17
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 {
+
+}