phalcon/cphalcon · error · Phalcon\Tag\Exception

The 'using' parameter is required

Error message

The 'using' parameter is required

What it means

Tag\Select::selectField (behind Tag::select() and Tag::selectStatic()) accepts options as an array, a Resultset, or any object. When options is an object (typically an ORM Resultset of models), Phalcon cannot know which model properties map to option value/label, so the 'using' parameter in the params array is mandatory; when fetch params['using'] fails, it throws Phalcon\Tag\Exception ("The 'using' parameter is required"). Array options never need 'using'.

Source

Thrown at phalcon/Tag/Select.zep:113

            if !fetch emptyText, params["emptyText"] {
                let emptyText = "Choose...";
            } else {
                unset params["emptyText"];
            }

            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)

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'using' to the first (params) argument: Tag::selectStatic(['categoryId', 'using' => ['id', 'name']], Categories::find())
2. In Volt: {{ select('categoryId', categories, ['using': ['id', 'name']]) }}
3. If you meant plain options, pass an array (e.g. Categories::find()->toArray() prepared as value=>label) — arrays need no 'using'

Example fix

// before
echo \Phalcon\Tag::selectStatic(['categoryId'], Categories::find()); // throws

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

$params = ['categoryId'];

if (is_object($options)) { // Resultset/object options require 'using'
    $params['using'] = $params['using'] ?? ['id', 'name'];
}

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

function needsUsingParameter($options): bool
{
    return is_object($options); // arrays never need 'using'
}

try {
    echo \Phalcon\Tag::selectStatic($params, $options);
} catch (\Phalcon\Tag\Exception $e) {
    if (str_contains($e->getMessage(), "'using' parameter is required")) {
        $params['using'] = ['id', 'name'];
        echo \Phalcon\Tag::selectStatic($params, $options);
    } else {
        throw $e;
    }
}

When it happens

Trigger: echo Tag::selectStatic(['categoryId'], Categories::find()); — a Resultset without 'using'; the same via Tag::select([...], $robots); 'using' present in the options/data array instead of the params array, so params['using'] is never found.

Common situations: Switching a select from static array options to Model::find() results without adding 'using'; Volt templates like {{ select('id', robots) }} missing the options map; params built dynamically where the 'using' key is dropped.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Only scalar values can be assigned to UI components
• The 'using' parameter should be an array
• Parameter 'using' requires two values
• Resultset returned an invalid value
• Class '{className}' is not an ADR Action.

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