phalcon/cphalcon · error · Phalcon\Html\Exceptions\UsingRequiresTwoValues

The 'using' parameter requires exactly two values

Error message

The 'using' parameter requires exactly two values

What it means

ResultsetData drives the Select helper from a Phalcon Resultset. Its constructor requires the $using array to hold exactly two entries — the column used for option values and the column used for option text — and throws UsingRequiresTwoValues immediately when count($using) !== 2.

Source

Thrown at phalcon/Html/Helper/Input/Select/ResultsetData.zep:61

    protected resultset;

    /**
     * @var array
     */
    protected using = [];

    /**
     * @param ResultsetInterface resultset
     * @param array              using
     * @param array              attributesMap
     */
    public function __construct(
        <ResultsetInterface> resultset,
        array using,
        array attributesMap = []
    ) {
        if unlikely count(using) !== 2 {
            throw new UsingRequiresTwoValues();
        }

        let this->resultset     = resultset;
        let this->using         = using;
        let this->attributesMap = attributesMap;
    }

    /**
     * Returns per-option attribute maps, keyed by option value.
     *
     * @return array
     */
    public function getAttributes() -> array
    {
        if null === this->resolvedAttributes {
            this->resolve();
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pass exactly two column names: ['id', 'name']
2. Validate count($using) === 2 before constructing the select helper
3. If you need extra per-option data, use the attributesMap or a separate lookup instead of a third using entry

Example fix

// before
$select->setUsing(['id', 'name', 'label']); // three entries

// after
$select->setUsing(['id', 'name']);

if (count($using) !== 2) {
    throw new \InvalidArgumentException(
        'The using parameter requires exactly two columns: [valueColumn, textColumn]'
    );
}

$data = new \Phalcon\Html\Helper\Input\Select\ResultsetData($resultset, $using, $attributesMap);

/** @param mixed $using */
function isUsingPair($using): bool
{
    return is_array($using) && count($using) === 2;
}

try {
    $data = new ResultsetData($resultset, $using, $attributesMap);
} catch (\Phalcon\Html\Exceptions\UsingRequiresTwoValues $e) {
    // misconfiguration: log and fall back to the first two columns
    error_log($e->getMessage());
    $data = new ResultsetData($resultset, array_slice($using, 0, 2), $attributesMap);
}

When it happens

Trigger: Passing a resultset to the select helper with using values like ['id'] (one column) or ['id', 'name', 'label'] (three columns); building the using list dynamically from configuration and ending up with an unexpected count.

Common situations: The classic 'using' option of Phalcon select inputs configured with the wrong column count; changing a query's selected columns and forgetting to update the value/text pair.

Related errors

• Resultset returned an invalid value
• 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/4464d3d14ef9a0df. Report an issue: GitHub.