phalcon/cphalcon · error · Phalcon\Translate\Exceptions\MissingRequiredParameter

Parameter 'directory' is required

Error message

Parameter 'directory' is required

What it means

The second mandatory Gettext option: prepareOptions() throws Phalcon\Translate\Exceptions\MissingRequiredParameter('directory') when options lacks 'directory' (phalcon/Translate/Adapter/Gettext.zep:296). The directory is where gettext looks for <locale>/<LC_CATEGORY>/<domain>.mo files — a string path or an array of paths.

Source

Thrown at phalcon/Translate/Adapter/Gettext.zep:296

        return [
            "category":      LC_ALL,
            "defaultDomain": "messages"
        ];
    }

    /**
     * Validator for constructor
     *
     * @phpstan-param translate_gettext_options $options
     */
    protected function prepareOptions( array options) -> void
    {
        if unlikely !isset options["locale"] {
            throw new MissingRequiredParameter("locale");
        }

        if unlikely !isset options["directory"] {
            throw new MissingRequiredParameter("directory");
        }

        let options = array_merge(
            this->getOptionsDefault(),
            options
        );

        this->setLocale(options["category"], options["locale"]);
        this->setDefaultDomain(options["defaultDomain"]);
        this->setDirectory(options["directory"]);
        this->setDomain(options["defaultDomain"]);
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'directory' => '/app/locales' (string) or an array of directories when catalogs live in several places.
2. Ensure the directory layout matches gettext expectations: <directory>/<locale>/LC_MESSAGES/<domain>.mo.
3. Validate both 'locale' and 'directory' keys before constructing when options are dynamic.

Example fix

// before
$t = new Gettext($factory, ['locale' => 'de_DE.UTF-8']);

// after
$t = new Gettext($factory, [
    'locale'        => 'de_DE.UTF-8',
    'directory'     => '/app/locales',
    'defaultDomain' => 'messages',
]);

$required = ['locale', 'directory'];
$missing = array_diff($required, array_keys($options));
if ($missing !== []) {
    throw new InvalidArgumentException('Gettext adapter missing options: ' . implode(', ', $missing));
}

When it happens

Trigger: new Gettext($factory, ['locale' => 'de_DE.UTF-8']) without 'directory'; passing the key as 'dir', 'path', or 'directories'.

Common situations: Config moved to a new structure and the directory entry dropped; single-locale dev setups where the directory was hardcoded then removed; the check order means locale errors surface first — fix locale, then this one appears.

Related errors

• Parameter 'locale' is required
• Parameter 'content' is required
• This class requires the gettext extension for PHP
• Translation content was not provided
• Cannot find translation key: {key}

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