/**
* throws exceptions if $item is not an indexable data type
*
* @param mixed $item
* the container to check
* @param string $exception
* the class to use when throwing an exception
* @return void
*/
public static function check($item, $exception = E4xx_UnsupportedType::class)
{
// make sure we have a string
if (!IsIndexable::check($item)) {
throw new $exception(SimpleType::from($item));
}
}
/**
* throws exceptions if $item is not a PHP trait that exists
*
* this is a wrapper around our IsDefinedTrait check
*
* @param mixed $item
* the container to check
* @param string $exception
* the class to use when throwing an exception
* @return void
*/
public static function check($item, $exception = E4xx_UnsupportedType::class)
{
// make sure we have a PHP class that exists
if (!IsDefinedTrait::check($item)) {
throw new $exception(SimpleType::from($item));
}
}
/**
* throws exceptions if $item is not a PHP class that exists
*
* this is a wrapper around our IsObjectOfType check
*
* @param mixed $item
* the container to check
* @param string $type
* the class or interface that we want to check against
* @param string $exception
* the class to use when throwing an exception
* @return void
*/
public static function check($item, $type, $exception = E4xx_UnsupportedType::class)
{
// robustness!
RequireStringy::check($type, $exception);
// make sure we have a PHP class that exists
if (!IsObjectOfType::check($item, $type)) {
throw new $exception(SimpleType::from($item));
}
}
/**
* throws exceptions if $item is not a PHP class or interface that exists
*
* this is a wrapper around our IsDefinedObjectType check
*
* @param mixed $item
* the container to check
* @param string $eNoSuchClass
* the exception to throw if $item isn't a valid PHP class
* @param string $eUnsupportedType
* the exception to throw if $item isn't something that we can check
* @return void
*/
public static function check($item, $eNoSuchClass = E4xx_NoSuchClass::class, $eUnsupportedType = E4xx_UnsupportedType::class)
{
RequireStringy::check($item, $eUnsupportedType);
if (trait_exists($item)) {
throw new $eUnsupportedType(SimpleType::from($item));
}
// make sure we have a PHP class that exists
if (!IsDefinedObjectType::check($item)) {
throw new $eNoSuchClass($item);
}
}
/**
* write an item of data to the stream
*
* this is the fallback when we do not know what else to write
*
* @param mixed $data
* the data to write
* @return void
*/
public function writeEverythingElse($data)
{
// force writing the data as a string
if (is_numeric($data)) {
$this->writeString((string) $data);
return;
}
if (is_bool($data)) {
$string = $data ? 'true' : 'false';
$this->writeString($string);
return;
}
throw new E4xx_UnsupportedType(SimpleType::from($data));
}
/**
* called when we have a data type that we cannot convert
*
* @param mixed $data
* the data to convert
* @return void
* @throws E4xx_UnsupportedType
*/
private static function nothingMatchesTheInputType($data)
{
throw new E4xx_UnsupportedType(SimpleType::from($data));
}
/**
* should we overwrite $ours[$key] with the value of $theirs?
*
* @param array $ours
* the array where $key may exist
* @param string $key
* the index on $ours whose fate we are deciding
* @param mixed $theirs
* the data we want to assign to the index
* @return boolean
* TRUE if we should overwrite the index's existing value
* with $value
* TRUE if $key currently has no value
* FALSE if we should merge $value into the index's exist
* value
*/
public static function intoArray($ours, $key, $theirs)
{
// robustness!
if (!IsIndexable::check($ours)) {
throw new E4xx_UnsupportedType(SimpleType::from($ours));
}
return self::checkArray($ours, $key, $theirs);
}
/**
* called when there's no entry in our dispatch table that matches
* $item's data type
*
* @param mixed $item
* the item that we cannot process
* @return void
*/
public static function nothingMatchesTheInputType($item)
{
throw new E4xx_UnsupportedType(SimpleType::from($item));
}
/**
* merge their data into our object
*
* @param object $ours
* the object that we want to merge into
* @param array|object $theirs
* the data that we want to merge from
* @return void
*/
public static function from($ours, $theirs)
{
if (IsAssignable::check($theirs)) {
return self::fromObject($ours, $theirs);
}
if (IsTraversable::check($theirs)) {
return self::fromArray($ours, $theirs);
}
// cannot merge anything that reaches here!
throw new E4xx_UnsupportedType(SimpleType::from($ours));
}
/**
* called by self::from when $input is an unsupported data type
*
* @param mixed $input
* @return void
*/
protected static function nothingMatchesTheInputType($input)
{
throw new E4xx_UnsupportedType(SimpleType::from($input));
}
/**
* merge their data into one of our data's properties
*
* @param mixed $ours
* the data that we want to merge into
* @param string $property
* the property to merge into
* @param mixed $value
* the data that we want to merge from
* @return void
*/
public static function of(&$ours, $property, $value)
{
if (IsIndexable::check($ours)) {
return self::ofArray($ours, $property, $value);
}
if (IsAssignable::check($ours)) {
return self::ofObject($ours, $property, $value);
}
throw new E4xx_UnsupportedType(SimpleType::from($ours));
}
/**
* @covers ::fromObject
*/
public function testCanStaticallyGetObjectType()
{
// ----------------------------------------------------------------
// setup your test
$data = new SimpleType();
$expectedType = SimpleType::class;
// ----------------------------------------------------------------
// perform the change
$actualType = SimpleType::fromObject($data);
// ----------------------------------------------------------------
// test the results
$this->assertEquals($expectedType, $actualType);
}
public function __construct($item, $path)
{
$type = SimpleType::from($item);
$msg = "'{$type}' at path '{$path}' is not a container";
parent::__construct(400, $msg);
}
/**
* exception thrown when we have been given two version numbers that are
* not compatible with each other
*
* @param mixed $a
* the LHS of the operation that was attempted
* @param mixed $b
* the RHS of the operation that was attempted
*/
public function __construct($a, $b)
{
$msgData = ['typeA' => SimpleType::from($a), 'typeB' => SimpleType::from($b)];
$msg = "RHS (of type '" . $msgData['typeB'] . "') is not compatible with LHS (of type '" . $msgData['typeA'] . "')";
parent::__construct(400, $msg, $msgData);
}
/**
* which method should we call on $target for $data?
*
* @param mixed $data
* the data we want to call $target with
* @param string|object $target
* the target that we want to call
* @param string $methodPrefix
* the prefix at the front of methods on $target
* @param string $eUnsupportedType
* the exception to throw if no matching method found
* @return string
* the method that suits $data the best
*
* @throws E4xx_UnsupportedType
*/
private static function findMethodToCall($data, $target, $methodPrefix, $eUnsupportedType = E4xx_UnsupportedType::class)
{
// is there a method that matches the data type?
if (($retval = self::findFirstMatchingMethod($data, $target, $methodPrefix)) !== null) {
return $retval;
}
// no match
//
// treat as an error
throw new $eUnsupportedType(SimpleType::from($data));
}
/**
* merge their data into our data, using dot.notation.support to
* find the point where the merge starts
*
* @param object $ours
* the object that we want to merge into
* @param string $path
* the dot.notation.support path to where the merge should start
* @param mixed $value
* the data that we want to merge from
* @param array|callable|string|null
* if $path goes beyond what exists in $ours, how do we want to
* extend $ours?
* @return void
*/
public static function into(&$ours, $path, $value, $extendingItem = null)
{
if (IsAssignable::check($ours)) {
return self::intoObject($ours, $path, $value, $extendingItem);
}
if (IsIndexable::check($ours)) {
return self::intoArray($ours, $path, $value, $extendingItem);
}
throw new E4xx_UnsupportedType(SimpleType::from($ours));
}
/**
* descend inside a container, using dot.notation.support, and optionally
* extending the container if the end of the dot.notation.path is missing
*
* @param mixed &$item
* the container to dig into
* @param string $property
* the dot.notation.support path to descend
* @param array|callable|string|null $extendingItem
* if we need to extend, what data type do we extend using?
* @return mixed
*/
public static function &into(&$item, $property, $extendingItem = null)
{
if (IsAssignable::check($item)) {
$retval =& self::intoObject($item, $property, $extendingItem);
return $retval;
}
if (IsTraversable::check($item)) {
$retval =& self::intoArray($item, $property, $extendingItem);
return $retval;
}
throw new E4xx_UnsupportedType(SimpleType::from($item));
}
