What causes "Value must be of type '{type}', '{actual}' given" in phalcon/cphalcon?

Cast values to the declared type before insert, e.g. (int) $age, or normalize the whole input array first

phalcon/cphalcon · error · Phalcon\Support\Collection\Exceptions\InvalidValueType

Value must be of type '{type}', '{actual}' given

Error message

Value must be of type '{type}', '{actual}' given

What it means

Phalcon\Support\Collection accepts a $type as its 4th constructor argument (also restored on unserialization). When a type is set, every value stored through init() or set() passes validateType(): the exact tokens 'int', 'string', 'bool', 'float', 'array', 'object' map to is_* checks, and any other string is treated as a class/interface name checked with instanceof. A value that fails the check throws Phalcon\Support\Collection\Exceptions\InvalidValueType (extends InvalidArgumentException) with "Value must be of type '{type}', '{actual}' given", where {actual} is gettype() of the rejected value.

Source

Thrown at phalcon/Support/Collection.zep:765

                break;
            case "bool":
                let ok = is_bool(value);
                break;
            case "float":
                let ok = is_float(value);
                break;
            case "array":
                let ok = is_array(value);
                break;
            case "object":
                let ok = is_object(value);
                break;
            default:
                let ok = (value instanceof this->type);
        }

        if (!ok) {
            throw new InvalidValueType(this->type, value);
        }
    }

    /**
     * @param mixed $value
     */
    private function checkSerializable(var value) -> mixed
    {
        if (
            typeof value === "object" &&
            true === method_exists(value, "jsonSerialize")
        ) {
            return value->jsonSerialize();
        }

        return value;
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

Cast values to the declared type before insert, e.g. (int) $age, or normalize the whole input array first
Use only the exact scalar tokens 'int', 'string', 'bool', 'float', 'array', 'object' — 'integer'/'boolean'/'double' are treated as class names and never match
If the payload is genuinely mixed, omit the type argument (null) and validate at the business layer
For class/interface types, ensure every value passes instanceof before set()/init()

Example fix

// before
$collection = new Collection(['age' => '30'], true, false, 'int'); // throws: '30' is string

// after
$collection = new Collection(['age' => (int) '30'], true, false, 'int');

Defensive patterns

Strategy: type-guard

Validate before calling

$type = 'int';
$data = ['age' => '30', 'posts' => 7];

foreach ($data as $key => $value) {
    if ('int' === $type && !is_int($value)) {
        $data[$key] = (int) $value; // or reject with your own error
    }
}

$collection = new Collection($data, true, false, $type);

Type guard

function acceptsCollectionType($value, string $type): bool
{
    switch ($type) {
        case 'int':    return is_int($value);
        case 'string': return is_string($value);
        case 'bool':   return is_bool($value);
        case 'float':  return is_float($value);
        case 'array':  return is_array($value);
        case 'object': return is_object($value);
        default:       return $value instanceof $type;
    }
}

Try / catch

use Phalcon\Support\Collection\Exceptions\InvalidValueType;

try {
    $collection->set('age', $age);
} catch (InvalidValueType $e) {
    // "Value must be of type 'int', 'string' given"
    $logger->warning($e->getMessage());
    $collection->set('age', (int) $age);
}

Prevention

Normalize scalar types at the system boundary — cast query/JSON/DB input once, before it reaches a typed collection
Use only the six recognized scalar tokens; anything else must be a real class/interface name
Wrap typed collections in factory methods that validate the whole payload before constructing
Unit-test every typed collection with edge values: null, numeric strings, empty arrays

When it happens

Trigger: new Collection(['age' => '30'], true, false, 'int') (numeric string vs int); new Collection(['u' => new stdClass()], true, false, DateTimeInterface::class)->set('u', 'nope'); using a non-token spelling like 'integer' or 'boolean', which falls through to instanceof and always fails; passing null, which fails every type check.

Common situations: Query params, JSON bodies, and DB/CSV drivers return numbers as strings, so a collection typed 'int'/'float' throws on the first insert. Rehydrating a typed collection with user input of shifted types. Declaring type 'integer'/'double' instead of the recognized tokens.

Related errors

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/15653447e2991675. Report an issue: GitHub.