<?php
declare( strict_types = 1 );
namespace Automattic\WooCommerce\Internal\Utilities;
use InvalidArgumentException;
/**
* Utilities to help ensure type safety.
*/
class Types {
/**
* Checks if $thing is an instance of $desired_type.
*
* If the check succeeds, $thing will be returned without further modification. If the check fails, then either
* an exception will be thrown or, if an $on_failure callback was supplied, it will be invoked to either generate
* an appropriate return value or to throw a more specific exception.
*
* Please note that the failure handler will be passed two arguments:
*
* $on_failure( $object, $desired_type )
*
* @since 9.1.0
* @throws InvalidArgumentException If $object does not match $desired_type, and an $on_failure callback was not supplied.
*
* @param mixed $thing The value or reference to be assessed.
* @param string $desired_type What we expect the return type to be, if it is not a WP_Error.
* @param ?callable $on_failure If provided, and if evaluation fails, this will be invoked to generate a return value.
*
* @return mixed
*/
public static function ensure_instance_of( $thing, string $desired_type, callable $on_failure = null ) {
// If everything looks good, return early.
if ( $thing instanceof $desired_type ) {
return $thing;
}
// Summarize the error for use in logging and in case we have to throw an exception.
$summary = sprintf(
'Object was not of expected type %1$s.',
$desired_type
);
// Otherwise, let's log the problem so the site operator has a record of where things went wrong.
$logger = wc_get_logger();
if ( $logger ) {
$logger->error(
$summary,
array(
'source' => 'wc-type-check-utility',
'backtrace' => true,
)
);
}
// Invoke the $on_failure handler, if specified.
if ( null !== $on_failure ) {
return $on_failure( $thing, $desired_type );
}
throw new InvalidArgumentException( esc_html( $summary ) );
}
}