Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Component\Assertion;
Chris@0: 
Chris@0: use Traversable;
Chris@0: 
Chris@0: /**
Chris@0:  * Generic inspections for the assert() statement.
Chris@0:  *
Chris@0:  * This is a static function collection for inspecting variable contents. All
Chris@0:  * functions in this collection check a variable against an assertion about its
Chris@0:  * structure.
Chris@0:  *
Chris@0:  * Example call:
Chris@0:  * @code
Chris@14:  *   assert(Inspector::assertAllStrings($array));
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * @ingroup php_assert
Chris@0:  */
Chris@0: class Inspector {
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts argument can be traversed with foreach.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed with foreach.
Chris@0:    */
Chris@0:   public static function assertTraversable($traversable) {
Chris@0:     return is_array($traversable) || $traversable instanceof Traversable;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts callback returns TRUE for each member of a traversable.
Chris@0:    *
Chris@0:    * This is less memory intensive than using array_filter() to build a second
Chris@0:    * array and then comparing the arrays. Many of the other functions in this
Chris@0:    * collection alias this function passing a specific callback to make the
Chris@0:    * code more readable.
Chris@0:    *
Chris@0:    * @param callable $callable
Chris@0:    *   Callback function.
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and $callable returns TRUE on
Chris@0:    *   all members.
Chris@0:    *
Chris@0:    * @see http://php.net/manual/language.types.callable.php
Chris@0:    */
Chris@0:   public static function assertAll(callable $callable, $traversable) {
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       foreach ($traversable as $member) {
Chris@0:         if (!$callable($member)) {
Chris@0:           return FALSE;
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are strings.
Chris@0:    *
Chris@0:    * Use this only if it is vital that the members not be objects, otherwise
Chris@0:    * test with ::assertAllStringable().
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are strings.
Chris@0:    */
Chris@0:   public static function assertAllStrings($traversable) {
Chris@0:     return static::assertAll('is_string', $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts all members are strings or objects with magic __toString() method.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are strings or
Chris@0:    *   objects with __toString().
Chris@0:    */
Chris@0:   public static function assertAllStringable($traversable) {
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       foreach ($traversable as $member) {
Chris@0:         if (!static::assertStringable($member)) {
Chris@0:           return FALSE;
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts argument is a string or an object castable to a string.
Chris@0:    *
Chris@0:    * Use this instead of is_string() alone unless the argument being an object
Chris@0:    * in any way will cause a problem.
Chris@0:    *
Chris@0:    * @param mixed $string
Chris@0:    *   Variable to be examined
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $string is a string or an object castable to a string.
Chris@0:    */
Chris@0:   public static function assertStringable($string) {
Chris@0:     return is_string($string) || (is_object($string) && method_exists($string, '__toString'));
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are arrays.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are arrays.
Chris@0:    */
Chris@0:   public static function assertAllArrays($traversable) {
Chris@0:     return static::assertAll('is_array', $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that the array is strict.
Chris@0:    *
Chris@0:    * What PHP calls arrays are more formally called maps in most other
Chris@0:    * programming languages. A map is a datatype that associates values to keys.
Chris@0:    * The term 'strict array' here refers to a 0-indexed array in the classic
Chris@0:    * sense found in programming languages other than PHP.
Chris@0:    *
Chris@0:    * @param mixed $array
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable is a 0-indexed array.
Chris@0:    *
Chris@0:    * @see http://php.net/manual/language.types.array.php
Chris@0:    */
Chris@0:   public static function assertStrictArray($array) {
Chris@0:     if (!is_array($array)) {
Chris@0:       return FALSE;
Chris@0:     }
Chris@0:     $i = 0;
Chris@0: 
Chris@0:     foreach (array_keys($array) as $key) {
Chris@0:       if ($i !== $key) {
Chris@0:         return FALSE;
Chris@0:       }
Chris@0:       $i++;
Chris@0:     }
Chris@0:     return TRUE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts all members are strict arrays.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are strict arrays.
Chris@0:    *
Chris@0:    * @see ::assertStrictArray
Chris@0:    */
Chris@0:   public static function assertAllStrictArrays($traversable) {
Chris@0:     return static::assertAll([__CLASS__, 'assertStrictArray'], $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts all given keys exist in every member array.
Chris@0:    *
Chris@0:    * Drupal has several data structure arrays that require certain keys be set.
Chris@0:    * You can overload this function to specify a list of required keys. All
Chris@0:    * of the keys must be set for this method to return TRUE.
Chris@0:    *
Chris@0:    * As an example, this assertion tests for the keys of a theme registry.
Chris@0:    *
Chris@0:    * @code
Chris@14:    *   assert(Inspector::assertAllHaveKey(
Chris@14:    *     $arrayToTest, "type", "theme path", "function", "template", "variables", "render element", "preprocess functions"));
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * Note: If a method requires certain keys to be present it will usually be
Chris@0:    * specific about the data types for the values of those keys. Therefore it
Chris@0:    * will be best to write a specific test for it. Such tests are either bound
Chris@0:    * to the object that uses them, or are collected into one assertion set for
Chris@0:    * the package.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    * @param string ...
Chris@0:    *   Keys to be searched for.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members have all keys.
Chris@0:    */
Chris@0:   public static function assertAllHaveKey($traversable) {
Chris@0:     $args = func_get_args();
Chris@0:     unset($args[0]);
Chris@0: 
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       foreach ($traversable as $member) {
Chris@0:         foreach ($args as $key) {
Chris@0:           if (!array_key_exists($key, $member)) {
Chris@0:             return FALSE;
Chris@0:           }
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are integer values.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are integers.
Chris@0:    */
Chris@0:   public static function assertAllIntegers($traversable) {
Chris@0:     return static::assertAll('is_int', $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are float values.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are floating point
Chris@0:    *   numbers.
Chris@0:    */
Chris@0:   public static function assertAllFloat($traversable) {
Chris@0:     return static::assertAll('is_float', $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are callable.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are callable.
Chris@0:    */
Chris@0:   public static function assertAllCallable($traversable) {
Chris@0:     return static::assertAll('is_callable', $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are not empty.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members not empty.
Chris@0:    */
Chris@0:   public static function assertAllNotEmpty($traversable) {
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       foreach ($traversable as $member) {
Chris@0:         if (empty($member)) {
Chris@0:           return FALSE;
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts all members are numeric data types or strings castable to such.
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are numeric.
Chris@0:    */
Chris@0:   public static function assertAllNumeric($traversable) {
Chris@0:     return static::assertAll('is_numeric', $traversable);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are strings that contain the specified string.
Chris@0:    *
Chris@0:    * This runs faster than the regular expression equivalent.
Chris@0:    *
Chris@0:    * @param string $pattern
Chris@0:    *   The needle to find.
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to examine.
Chris@0:    * @param bool $case_sensitive
Chris@0:    *   TRUE to use strstr(), FALSE to use stristr() which is case insensitive.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are strings
Chris@0:    *   containing $pattern.
Chris@0:    */
Chris@0:   public static function assertAllMatch($pattern, $traversable, $case_sensitive = FALSE) {
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       if ($case_sensitive) {
Chris@0:         foreach ($traversable as $member) {
Chris@0:           if (!(is_string($member) && strstr($member, $pattern))) {
Chris@0:             return FALSE;
Chris@0:           }
Chris@0:         }
Chris@0:       }
Chris@0:       else {
Chris@0:         foreach ($traversable as $member) {
Chris@0:           if (!(is_string($member) && stristr($member, $pattern))) {
Chris@0:             return FALSE;
Chris@0:           }
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are strings matching a regular expression.
Chris@0:    *
Chris@0:    * @param string $pattern
Chris@0:    *   Regular expression string to find.
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are strings
Chris@0:    *   matching $pattern.
Chris@0:    */
Chris@0:   public static function assertAllRegularExpressionMatch($pattern, $traversable) {
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       foreach ($traversable as $member) {
Chris@0:         if (!is_string($member)) {
Chris@0:           return FALSE;
Chris@0:         }
Chris@0: 
Chris@0:         if (!preg_match($pattern, $member)) {
Chris@0:           return FALSE;
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that all members are objects.
Chris@0:    *
Chris@0:    * When testing if a collection is composed of objects those objects should
Chris@0:    * be given a common interface to implement and the test should be written to
Chris@0:    * search for just that interface. While this method will allow tests for
Chris@0:    * just object status or for multiple classes and interfaces this was done to
Chris@0:    * allow tests to be written for existing code without altering it. Only use
Chris@0:    * this method in that manner when testing code from third party vendors.
Chris@0:    *
Chris@0:    * Here are some examples:
Chris@0:    * @code
Chris@0:    *   // Just test all are objects, like a cache.
Chris@14:    *   assert(Inspector::assertAllObjects($collection));
Chris@0:    *
Chris@0:    *   // Test if traversable objects (arrays won't pass this)
Chris@14:    *   assert(Inspector::assertAllObjects($collection, '\\Traversable'));
Chris@0:    *
Chris@0:    *   // Test for the Foo class or Bar\None interface
Chris@14:    *   assert(Inspector::assertAllObjects($collection, '\\Foo', '\\Bar\\None'));
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * @param mixed $traversable
Chris@0:    *   Variable to be examined.
Chris@0:    * @param string ...
Chris@0:    *   Classes and interfaces to test objects against.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if $traversable can be traversed and all members are objects with
Chris@0:    *   at least one of the listed classes or interfaces.
Chris@0:    */
Chris@0:   public static function assertAllObjects($traversable) {
Chris@0:     $args = func_get_args();
Chris@0:     unset($args[0]);
Chris@0: 
Chris@0:     if (static::assertTraversable($traversable)) {
Chris@0:       foreach ($traversable as $member) {
Chris@0:         if (count($args) > 0) {
Chris@0:           foreach ($args as $instance) {
Chris@0:             if ($member instanceof $instance) {
Chris@0:               // We're continuing to the next member on the outer loop.
Chris@0:               // @see http://php.net/continue
Chris@0:               continue 2;
Chris@0:             }
Chris@0:           }
Chris@0:           return FALSE;
Chris@0:         }
Chris@0:         elseif (!is_object($member)) {
Chris@0:           return FALSE;
Chris@0:         }
Chris@0:       }
Chris@0:       return TRUE;
Chris@0:     }
Chris@0:     return FALSE;
Chris@0:   }
Chris@0: 
Chris@0: }