phalcon/cphalcon · error · Phalcon\Tag\Exception

The 'using' parameter should be an array

Error message

The 'using' parameter should be an array

What it means

Even when 'using' is present for a select built from object options, it must be structured data: Tag\Select rejects a $using that is neither array nor object with Phalcon\Tag\Exception ("The 'using' parameter should be an array") — despite the message, an object also passes; strings and other scalars throw. The intended shape is ['valueColumn', 'labelColumn'].

Source

Thrown at phalcon/Tag/Select.zep:117

            }

            unset params["useEmpty"];
        }

        if !fetch options, params[1] {
            let options = data;
        }

        if typeof options == "object" {
            /**
             * The options is a resultset
             */
            if unlikely !fetch using, params["using"] {
                throw new Exception("The 'using' parameter is required");
            }

            if unlikely (typeof using != "array" && typeof using != "object") {
                throw new Exception(
                    "The 'using' parameter should be an array"
                );
            }
        }

        unset params["using"];

        let code = BaseTag::renderAttributes("<select", params) . ">" . PHP_EOL;

        if useEmpty {
            /**
             * Create an empty value
             */
            let code .= self::echoOption(emptyValue)
                . emptyText
                . "</option>" . PHP_EOL;
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Wrap it in an array with value and label columns: 'using' => ['id', 'name']
2. Normalize dynamic params before the call: $params['using'] = (array) $params['using'];
3. Split comma strings: array_map('trim', explode(',', $using))

Example fix

// before
echo \Phalcon\Tag::selectStatic(['categoryId', 'using' => 'id'], Categories::find());

// after
echo \Phalcon\Tag::selectStatic(
    ['categoryId', 'using' => ['id', 'name']],
    Categories::find()
);

if (isset($params['using']) && !is_array($params['using']) && !is_object($params['using'])) {
    $params['using'] = (array) $params['using']; // 'id' -> ['id']
}

echo \Phalcon\Tag::selectStatic($params, $resultset);

function isValidUsingParameter($using): bool
{
    return is_array($using) || is_object($using);
}

try {
    echo \Phalcon\Tag::selectStatic($params, $resultset);
} catch (\Phalcon\Tag\Exception $e) {
    if (str_contains($e->getMessage(), "'using' parameter should be an array")) {
        $params['using'] = (array) $params['using'];
        echo \Phalcon\Tag::selectStatic($params, $resultset);
    } else {
        throw $e;
    }
}

When it happens

Trigger: 'using' => 'id' — a single column string instead of an array; 'using' => 0 or another scalar; dynamically built params where the using list is sometimes a bare string.

Common situations: Single-column selects where developers pass the column name directly; config-driven column names arriving as a string like 'id,name' instead of an array.

Related errors

• The 'using' parameter is required
• Parameter 'using' requires two values
• Resultset returned an invalid value
• Unknown method: [{method}]
• The index 'tables' is required in the definition array

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