What causes "Field must be passed as array of fields or string" in phalcon/cphalcon?

Pass a string field name: $validation->add('email', new PresenceOf())

phalcon/cphalcon · error · Phalcon\Filter\Validation\Exceptions\InvalidFieldType

Field must be passed as array of fields or string

Error message

Field must be passed as array of fields or string

What it means

Validation::add(field, validator) accepts a single field name as a string, or a list of field names as an array (the array form with a combined-fields validator registers a scope). InvalidFieldType is thrown when field is any other type — int, float, bool, null, or object.

Source

Thrown at phalcon/Filter/Validation.zep:152

     * @return static
     */
    public function add(var field, <ValidatorInterface> validator) -> <static>
    {
        var singleField;

        if typeof field === "array" {
            // Uniqueness validator for combination of fields is handled differently
            if validator instanceof AbstractCombinedFieldsValidator {
                let this->combinedFieldsValidators[] = [field, validator];
            } else {
                for singleField in field {
                    let this->validators[singleField][] = validator;
                }
            }
        } elseif typeof field == "string" {
            let this->validators[field][] = validator;
        } else {
            throw new InvalidFieldType();
        }

        return this;
    }

    /**
     * Appends a message to the messages list
     *
     * @param MessageInterface $message
     */
    public function appendMessage(<MessageInterface> message) -> <static>
    {
        this->messages->appendMessage(message);

        return this;
    }

    /**

View on GitHub (pinned to b7419de9cd)

Solutions

Pass a string field name: $validation->add('email', new PresenceOf())
For several fields at once pass an array of strings: $validation->add(['email', 'name'], new PresenceOf())
When the name is dynamic, cast/verify it: is_string($field) || (is_array($field) && $field) before calling add()

Example fix

// before
foreach ($row as $key => $value) {
    $validation->add($key, new PresenceOf()); // $key = 0 throws InvalidFieldType
}

// after
foreach ($row as $key => $value) {
    if (is_string($key)) {
        $validation->add($key, new PresenceOf());
    }
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (!is_string($field) && !is_array($field)) {
    throw new InvalidArgumentException('Field must be string or array of strings, got ' . get_debug_type($field));
}
$validation->add($field, $validator);

Type guard

function isValidFieldName($field): bool
{
    if (is_string($field)) { return $field !== ''; }
    return is_array($field) && $field !== [] && array_all($field, 'is_string');
}

Try / catch

use Phalcon\Filter\Validation\Exceptions\InvalidFieldType;
try {
    $validation->add($dynamicField, $validator);
} catch (InvalidFieldType $e) {
    throw new InvalidArgumentException('Rejected dynamic field name: ' . get_debug_type($dynamicField), 0, $e);
}

Prevention

Never feed raw array_keys() of user data into add(); whitelist field names instead
Use string field constants shared between form definitions and validation setup

When it happens

Trigger: $validation->add(0, new PresenceOf()) from looping over numeric-indexed input; $validation->add($config['field'], ...) where the config key is missing so null is passed; passing a field object instead of its name string.

Common situations: Field names taken from array_keys() of a numerically indexed payload; dynamic validator building from request data where the key does not exist; refactors that turn field constants into undefined values.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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