PHPOffice/PHPWord · error · InvalidArgumentException

Invalid option '$optionkey', possible values are ' …

Error message

Invalid option '$optionkey', possible values are ' . implode(', ', $this->fieldsArray[$this->type]['options'])

What it means

Field::setOptions() validates each option key against the per-type 'options' list in $fieldsArray, throwing InvalidArgumentException with the list of valid options in the message. Keys starting with a backslash are allowed through (treated as raw field switches). This guards the generated Word field instruction switches.

Solutions

1. Use only option keys defined in Field::$fieldsArray for your field type; the exception message lists them.
2. Prefix custom/raw switches with a backslash (e.g. '\h') to bypass the whitelist.
3. Verify setType() was called first — an empty type yields an empty options whitelist.
4. Catch InvalidArgumentException when options come from user config.

Example fix

// before
$field->setOptions(['Bold' => true]);
// after
$field->setOptions(['\b' => true]);

foreach (array_keys($options) as $k) {
    if (!str_starts_with($k, '\\') && !in_array($k, $allowedOptions, true)) {
        unset($options[$k]);
    }
}

function isRawSwitch(string $key): bool { return $key !== '' && $key[0] === '\\'; }

try { $field->setOptions($opts); } catch (\InvalidArgumentException $e) { log($e->getMessage()); }

When it happens

Trigger: Calling $field->setOptions(['Bogus' => true]) where 'Bogus' is not in $fieldsArray[$this->type]['options'] and does not start with '\'.

Common situations: Using option names from a different field type, typos in switch names, or hand-rolling switches without the leading backslash escape.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid type '$type'
• Invalid property '$propkey'
• Invalid value, on of ' . implode(', ', $position) . '…
• Invalid value, on of ' . implode(', ', $restartNumbers) . '…
• Invalid value, dirty or clean possible

AI-assisted analysis of PHPOffice/PHPWord@aef95c0415 (2026-09-14). Data as JSON: /api/errors/9d882c4930c7c7cf. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/Element/Field.php:253

     * Get Field properties.
     *
     * @return array
     */
    public function getProperties()
    {
        return $this->properties;
    }

    /**
     * Set Field options.
     *
     * @return self
     */
    public function setOptions(array $options = [])
    {
        foreach (array_keys($options) as $optionkey) {
            if (!(isset($this->fieldsArray[$this->type]['options'][$optionkey])) && substr($optionkey, 0, 1) !== '\\') {
                throw new InvalidArgumentException("Invalid option '$optionkey', possible values are " . implode(', ', $this->fieldsArray[$this->type]['options']));
            }
        }
        $this->options = array_merge($this->options, $options);

        return $this;
    }

    /**
     * Get Field properties.
     *
     * @return array
     */
    public function getOptions()
    {
        return $this->options;
    }

    /**

View on GitHub (pinned to aef95c0415)